| name | tesseract |
| description | Use when you've been poking at the same file, concept, or problem across many sessions and want to step outside time to see its whole arc — or when you want to leave a note for next-session-you. Triggers: 'I've been going in circles on X', 'what have I learned about X', 'what did past-me say about X', 'I keep rediscovering this'. |
| user-invocable | true |
| argument-hint | [anchor] [--signal "<morse>"] [--retro] | --visual [--out <path>] |
/tesseract — Step Outside Time
"Maybe she already knows I'm here. Maybe I already told her." — Cooper
Gravity — file I/O — is the only force that crosses the session-dimension.
Past-you left signals on the shelf; present-you is about to leave one too. You
cannot visit the tesseract silently.
Arguments: $ARGUMENTS
Metaphor
| Movie | Skill |
|---|
| Murph point of reference | Anchor — the file/branch/topic everything is framed around |
| Gravity | File I/O — the only cross-session channel |
| Books on the shelf | Shelf entries at ~/.tesseract/shelf/<slug>.md |
| Morse via the watch | --signal "<morse>" — optional short payload |
| Bulk-beings transmission | ~/.tesseract/bulk-beings.md — append-only self-log |
| Four hallways | git · memory · shelf · bulk — the four evidence streams |
Process
0 · --visual short-circuit
If $ARGUMENTS contains the bare flag --visual, do not resolve an anchor, do
not read hallways, and do not drop a book. Instead:
- Parse
--out <path> if present (default /tmp/visual-aid-tesseract.html).
- Run the skill's bundled renderer:
python3 ~/.claude/skills/tesseract/render_visual.py --out <path>
- Print only the
file:// URL on its own line.
--visual is read-only by design: it surveys the whole shelf, which is not a
visit to any single anchor, so writing a shelf block + bulk-beings line would
pollute the ledger with meta-entries. See the test contract in
tests/test_render_visual.py::test_cli_visual_writes_html_and_does_not_touch_shelf_or_bulk.
1 · Resolve the anchor
Parse $ARGUMENTS in two passes — first strip the standalone --retro flag,
then split on --signal. Treat a quoted --signal "..." value as opaque signal
text while parsing flags: tokens inside that quoted string are not scanned for
--retro or any other flag syntax.
-
--retro pass. If the standalone token --retro appears in $ARGUMENTS
outside any quoted --signal value, set retro=true and remove that token
from the argument string. If no such standalone token appears, retro=false.
Order-independent among top-level arguments: --retro may sit before the
anchor, between anchor and --signal, or after the signal value; if
--signal is also present, only a separate standalone --retro token outside
the quoted signal value counts.
-
--signal split. With --retro removed, split the remainder on
--signal (surrounded by spaces). Left side (trimmed) → anchor. Right side
must begin with a delimited value → signal. Accepted delimiter forms:
"..." (canonical double-quote) or {...} (brace-form, symmetric with
--anchors {a,b,c}). Both are equivalent — pick whichever reads better in
context. Brace-form is parsed as a single opaque value even if it contains
commas (no per-comma split — that's reserved for the --anchors multi-value
syntax). If --signal appears but no delimited value follows, print a
one-line warning and fall back to the default signal.
-
--retro + --signal combination. If retro=true and --signal was
provided, print a one-line warning ((retro mode — ignoring --signal)) and
discard the signal entirely — do not write, log, or emit it in the rendered
output. Retro is observation-only; a signal is a transmission, and the two
contradict.
-
If the left side starts with --anchor , strip that prefix and treat the
remainder as the anchor value. Lets /tesseract --anchor foo --signal "bar"
resolve to anchor=foo without literally naming the flag.
-
If anchor is empty, cascade:
- First line of
git status --porcelain | head -1; strip the three-char
status prefix (two status chars + one space) to get the path. For
rename/copy entries (status code R or C), the path-section is
— use the part after (the destination path).
Slug rule. Lowercase the anchor. Replace every run of characters outside
[a-z0-9] with a single -. Trim leading and trailing -. This lowercases
letters and collapses every run of non-[a-z0-9] characters (dots, slashes,
spaces, etc.) into a single -.
| Anchor | Slug |
|---|
src/widgets/Button.tsx | src-widgets-button-tsx |
feat/widget-cleanup | feat-widget-cleanup |
hooks/block-inline-scripts.py | hooks-block-inline-scripts-py |
core-memories | core-memories |
"memory-system-redesign" | memory-system-redesign |
Print > Murph point: <anchor> before any other output — the reference frame
must be explicit from character one.
Default signal when --signal is absent: — (em dash). The empty Morse
still counts as a visit, and does not contradict the "signals are short" rule
below.
Multi-anchor form. /tesseract --anchors {a,b,c} --signals "<morse>" loops
the book-drop logic (steps 3–7) per anchor, processing left-to-right in argument
order so output ordering matches argument order. --signals is a synonym/alias
of --signal — one signal applies to all anchors; the plural spelling is
flag-symmetry, not N-signals semantics. Per-anchor reports are concatenated and
separated by --- (horizontal rule) so the operator can visually scan the
boundary between reports.
Edge cases:
--anchors {} (empty brace) is degenerate; fall back to the anchor-resolution
cascade above as if no anchor flag were given.--anchors {solo} (singleton brace) behaves as a single one-anchor invocation
— same as /tesseract solo. No loop, no --- separator.
The singular --anchor and --signal forms remain unchanged. Multi-anchor is
additive, not a replacement.
2 · Ensure the tesseract exists
If retro=true, skip this step entirely — read-only invocations may not
create directories. Step 3 already handles the missing-file case gracefully
(N_before = 0), and Hallway 3 renders (no prior signals — first visit) if
the shelf dir is absent. Creating the directory in retro mode would mutate
file-system state ("absent" → "present empty dir"), which violates the
observation-only invariant.
For non-retro invocations, if ~/.tesseract/shelf is absent, mkdir -p it.
bulk-beings.md is created implicitly by the first append.
3 · Read the shelf
With Read, open ~/.tesseract/shelf/<slug>.md if it exists. Count every
^## block — call that count N_before. Take the three most-recent blocks for
Hallway 3. If the file doesn't exist, N_before = 0.
4 · Read bulk-beings
With Read, open ~/.tesseract/bulk-beings.md if it exists. Collect lines
where the anchor string appears case-insensitively. Keep up to three
most-recent. Do not pad with unrelated lines at this step; Hallway 4 handles
the fallback labeling.
5 · Render the four hallways
Each hallway expresses time relative to the anchor — 3 commits ago,
11d ago, 5 days since last signal. Never render absolute ISO timestamps
inside a hallway (storage is a separate concern — see step 6).
Hallway 1 — git time-strings. Run a precondition check first:
git rev-parse --is-inside-work-tree 2>/dev/null. If this exits non-zero (cwd
isn't a git repository), print (not in a git repository — Hallway 1 silent)
and skip the cascade entirely. Do not synthesize a custom message ("not in a
git repo at /path/x") and do not fall through to the free-text grep — both
leak cwd or produce noise.
Otherwise cascade; stop at first match:
git ls-files --error-unmatch "<anchor>" exits 0 → tracked path:
git log --follow --max-count=5 --pretty='format:%h %ar — %s' -- "<anchor>".git branch --list "<anchor>" is non-empty → branch:
git log --max-count=5 --pretty='format:%h %ar — %s' "<anchor>".- Anchor contains
/ OR has an extension → path-heuristic (new or
untracked file):
git log --follow --max-count=5 --pretty='format:%h %ar — %s' -- "<anchor>".
- Else → free text:
git log --max-count=5 -i -F --grep="<anchor>" --pretty='format:%h %ar — %s'.
If the chosen branch returns no commits, print
(no commits touching this anchor). Checking branches before the path-heuristic
fixes the misclassification where anchors like feat/foo (a real branch) were
routed to --follow.
Hallway 2 — memory resonance. Query = basename-without-extension if anchor
is path-like, else the anchor itself.
grep -l -i -F -- "<query>" ~/.claude/projects/*/memory/*.md 2>/dev/null | head -5
For each matching file (cap 5 files, one line each), read its name:
frontmatter. If missing, use the first ^# heading. If still missing, the
basename without .md. Report mtime-age in days from now:
- <label> — <d>d ago — <path>. If no files match, print
(no memory resonance).
Hallway 3 — shelf. From step 3's loaded blocks, most-recent first, one line
each: - <d>d ago — "<signal>". If none, (no prior signals — first visit).
Hallway 4 — bulk-beings. From step 4:
- ≥1 anchor-matching line → print them verbatim, newest first.
- 0 anchor-matching lines but bulk-beings exists → print
(no lines touched this anchor — last transmissions overall:) then the file's
last three lines.
- bulk-beings doesn't exist →
(silence — no prior transmissions).
6 · Drop a book (leave gravity signals)
Retro short-circuit. If retro=true, skip this entire step. In retro mode
the skill does not prepend a shelf block and does not append a
bulk-beings line — no <ts>, no printf, no Write to either file. Retro is
observation-only: you are looking at the tesseract from outside; you are not
adding a book to its shelf. Skip directly to step 7.
For non-retro invocations, continue:
<ts> = date -u +%Y-%m-%dT%H:%M:%SZ. ISO timestamps live only in stored shelf
blocks, never in rendered hallway output.
Shelf prepend. Read the existing shelf file (empty string if absent).
Concatenate this block at the top:
## <ts>
anchor: <anchor>
signal: <signal>
hallways: 4
If the file didn't exist, include a leading # Shelf — <anchor> heading above
the first block, then the block. Write the result back with Write.
Bulk-beings append. One shell call, one line:
printf '%s — %s — %s\n' "$ts" "$anchor" "$learning" >> ~/.tesseract/bulk-beings.md
Multi-anchor caveat. When --anchors {a,b,c} produces N appends, do not
chain them with && in a single Bash call — three printfs joined by && will
already hit the per-Bash 3-separator hook cap (see "Rules of the bulk" →
"Hook-compliant shell"). Issue one Bash call per anchor (each call is one
statement, one separator), or fall back to Read + Write.
If the full append command would exceed the 300-char hook cap (see "Rules of the
bulk"), do not shorten the learning — it's load-bearing for future-you. Fall
back to Read + Write like the shelf: read bulk-beings.md, append the new
line to the end, write back in a single atomic write.
<one-line-learning> must cite something concrete from this invocation's
hallways or context — a specific commit hash, a resonance pattern, a
contradiction between two signals, an absence, a coincidence of dates. A
sentence future-you can verify. Never "visited the anchor" or any other generic.
If nothing stood out, note that explicitly:
no new information — four hallways silent.
7 · Render the final output
The header line and the trailer differ between normal and retro mode. The four
hallway sections are identical in both.
Normal mode (retro=false):
# 🧊 Tesseract: <anchor>
> Murph point. 4 hallways in view. <N> prior visits on the shelf.
## Hallway 1 — git time-strings
<hallway 1>
## Hallway 2 — memory resonance
<hallway 2>
## Hallway 3 — the shelf (gravity signals)
<hallway 3>
## Hallway 4 — bulk-beings transmission
<hallway 4>
---
## 📉 Dropped a book
Shelf: ~/.tesseract/shelf/<slug>.md (+1 entry)
Bulk beings: ~/.tesseract/bulk-beings.md (+1 line)
Signal: "<signal>"
Learning: <one-line-learning>
Retro mode (retro=true): the header carries a [retro …] marker, and the
📉 Dropped a book block is replaced with an 👁️ Observed only block that
affirms the read-only nature of the visit.
# 🧊 Tesseract: <anchor>
> Murph point [retro — observing from outside]. 4 hallways in view. <N> prior visits on the shelf.
## Hallway 1 — git time-strings
<hallway 1>
## Hallway 2 — memory resonance
<hallway 2>
## Hallway 3 — the shelf (gravity signals)
<hallway 3>
## Hallway 4 — bulk-beings transmission
<hallway 4>
---
## 👁️ Observed only — no book dropped
Shelf: ~/.tesseract/shelf/<slug>.md (unchanged)
Bulk beings: ~/.tesseract/bulk-beings.md (unchanged)
Mode: retro (no shelf prepend, no bulk-beings append)
<N> is N_before — the count of visits before this invocation's shelf
write. On a first visit this reads 0 prior visits, which is correct: the
current invocation's own book-drop isn't prior to itself. Retro mode performs no
write, so N_before simply equals the current shelf count for that anchor.
Rules of the bulk
- Gravity is file I/O. Nothing else crosses sessions. Do not try to remember
state any other way inside this skill.
- Every non-retro invocation drops a book. Reads in normal mode are never
silent — one shelf entry AND one bulk-beings line, every time. The single
exemption is
--retro, which is observation-only: it skips both writes by
design (see step 6's retro short-circuit). Do not rationalize a retro
invocation back into a write — retro means no book.
- Anchor-relative time in the hallways. ISO timestamps are fine inside shelf
block headers (storage), never in rendered hallway output.
- Bulk-beings is append-only. Never truncate, never rewrite.
- Signals stay short. One line, ≤80 chars. If you need a paragraph, that's a
memory entry, not a signal.
- Learning must be concrete. Cite a hash, a date, a file, a specific
pattern. The filler "visited — …" line is banned.
- Strip newlines before append. Before the bulk-beings append, replace any
\n or \r in <anchor> and <one-line-learning> with a single space. A
literal newline in either field would smuggle a second log line and break the
one-entry-per-line invariant Hallway 4 depends on. (Other shell metacharacters
— ", $, `, \ — are safe under printf '%s' "$var", which doesn't
expand its arguments.)
- Hook-compliant shell. Per-Bash-call cap: 300 chars and 3 statement
separators (
;, &&, ||, |, >, <, >>, <<, newline). For anything
longer or multi-step, write a helper to /tmp/ with Write first — see
this repo's CLAUDE.md "No Inline Non-Bash Scripts in Bash" rule.
- Race condition is accepted. Two concurrent
/tesseract invocations on the
same anchor may lose a shelf entry. This is a solo skill; no locking.
Examples
/tesseract hooks/block-inline-scripts.py — path anchor. Hallway 1 uses
--follow./tesseract feat/tesseract-skill — branch anchor. Hallway 1 passes the branch
to git log./tesseract "memory-system-redesign" — free-text anchor. Hallway 1 falls to
--grep./tesseract core-memories --signal "keep it under 200 lines" — drops Morse
for next-session-you./tesseract — infers anchor via modified-file → branch → latest-memory
cascade. Prints the inferred anchor first so the frame is explicit./tesseract --visual — read-only survey: renders every shelf entry as a
single self-contained HTML page at /tmp/visual-aid-tesseract.html. No
anchor, no hallways, no shelf/bulk write. Add --out <path> to redirect./tesseract core-memories --retro — pure observation. Renders the four
hallways for core-memories but performs no shelf prepend and no
bulk-beings append. Use when you want to look up past-you's signals without
becoming a new signal yourself./tesseract --retro feat/widget-cleanup — retro on a branch anchor.
Order-independent: --retro may sit anywhere in the argument string./tesseract --anchors {learn,insights} --signals "auto-report ready" — fans
out across two anchors in argument order; per-anchor reports are rendered
back-to-back, separated by ---.
Notes
- Code ships, data doesn't. The skill itself —
SKILL.md and any supporting
scripts under skills/tesseract/ — is safe to ship with the claude-damn
plugin. The gravity signals at ~/.tesseract/shelf/*.md and
~/.tesseract/bulk-beings.md are personal and must never be committed.
Any repo that mirrors ~/.claude should gitignore ~/.tesseract/ entirely.
Don't bake specific anchors, signals, or paths into source — read the shelf at
runtime.
- No subagents, no
shared/ coordination, no tests. A solo skill that
communicates only with its own past and future, and only through gravity.
- The bootstrap paradox: the content of
bulk-beings.md is what teaches the
next invocation what this anchor's landscape contains. Future-you built this
interface for past-you by using it.
- Shared helpers. The slug rule, anchor cascade, and shelf parser are
factored into
skills/_shared/ (slugify.py, anchor.py, parse_shelf.py)
so /atlas and any future Python entrypoint can reuse them without copy-paste
drift. Today this skill remains prose-only — the reference is informational,
not a Python import you need to make. When a future change adds Python here,
import from skills/_shared/ rather than inlining.
