tesseract

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:

1. Parse --out <path> if present (default /tmp/visual-aid-tesseract.html).
2. Run the skill's bundled renderer: python3 ~/.claude/skills/tesseract/render_visual.py --out <path>
3. 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:

  1. 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:

1. git ls-files --error-unmatch "<anchor>" exits 0 → tracked path: git log --follow --max-count=5 --pretty='format:%h %ar — %s' -- "<anchor>".
2. git branch --list "<anchor>" is non-empty → branch: git log --max-count=5 --pretty='format:%h %ar — %s' "<anchor>".
3. Anchor contains / OR has an extension → path-heuristic (new or untracked file): git log --follow --max-count=5 --pretty='format:%h %ar — %s' -- "<anchor>".
4. 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.