tesseract
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'.
- License 许可
- MIT
- 最近更新
- 2026-09-10
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- 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'.
- argument-hint
- [anchor] [--signal "<morse>"] [--retro] | --visual [--out <path>]
- user-invocable
- true
02 资源文件 7
- 参考文档evals/iteration-1/baseline/pressure/rationalizations.md2.8 KB
- 脚本render_visual.py21.9 KB
- 参考文档tests/fixtures/bulk-beings.md357 B
- 参考文档tests/fixtures/shelf/alpha.md238 B
- 参考文档tests/fixtures/shelf/beta.md80 B
- 参考文档tests/fixtures/shelf/src-widgets-button-tsx.md207 B
- 脚本tests/test_render_visual.py5.9 KB
03 SKILL.md 正文
/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.
-
--retropass. If the standalone token--retroappears in$ARGUMENTSoutside any quoted--signalvalue, setretro=trueand remove that token from the argument string. If no such standalone token appears,retro=false. Order-independent among top-level arguments:--retromay sit before the anchor, between anchor and--signal, or after the signal value; if--signalis also present, only a separate standalone--retrotoken outside the quoted signal value counts. -
--signalsplit. With--retroremoved, 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--anchorsmulti-value syntax). If--signalappears but no delimited value follows, print a one-line warning and fall back to the default signal. -
--retro+--signalcombination. Ifretro=trueand--signalwas 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 toanchor=foowithout literally naming the flag. -
If
anchoris 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 codeRorC), the path-section isold -> new— use the part after->(the destination path). git branch --show-current.ls -t ~/.claude/projects/*/memory/*.md 2>/dev/null | head -1→ itsname:frontmatter field; if none, the basename without.md.ls -t ~/.tesseract/shelf/*.md 2>/dev/null | head -1→ filename stem. Past-you's last anchor, recovered from the shelf itself.basename "$PWD". Where you are when history is empty.
If every step yields nothing (first-ever invocation outside any repo with empty memory and empty shelf), use the literal string
(unknown)as the anchor and call that out in the one-line-learning. - First line of
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
\nor\rin<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 underprintf '%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
/tesseractinvocations 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 togit 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 forcore-memoriesbut 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:--retromay 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.mdand any supporting scripts underskills/tesseract/— is safe to ship with theclaude-damnplugin. The gravity signals at~/.tesseract/shelf/*.mdand~/.tesseract/bulk-beings.mdare personal and must never be committed. Any repo that mirrors~/.claudeshould 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.mdis 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/atlasand 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 fromskills/_shared/rather than inlining.
04 同仓库更多 Skills
visual-aid
Use when the user asks for a quick visual aid, visual explainer, concept card, one-pager, poster, cheat sheet, infographic, visual summary, summary card, or mini explainer page — especially from input like a block of text, attached images, an attached song (lyrics/audio), a web link, a CSV/dataset, a math formula, a code snippet to walk through, a tutorial's steps, a timeline, or an A-vs-B comparison. Triggers include "make me a quick visual aid", "turn this into a one-pager / cheat sheet / explainer", "summarize this visually", "give me a visual of", "explain this on a single page", "make a concept card for", "whip up a page about", "build a mini page that shows", "something I can paste into a doc explaining X", or any request to render a topic/text/link/image-set/song/data into a standalone page. Prefer this skill over frontend-design when the ask is an explanatory single-file page (not a production UI), over playground when the output is static information display (not an interactive configurator), and over a Markdown/code answer when the user explicitly wants a *page* (HTML). Produces a single self-contained HTML file that opens on double-click without a server.
tdd
Invoke test-driven development as an explicit one-at-a-time micro-cycle — one test, one piece of functionality, refactor, then repeat for the next behavior
tdd-cat
TDD workflow with subagent-driven-development — /tdd composed with /cat, plus the A/B TDD execution-mode axis (split-phase vs micro-cycle) asked as a third question in /cat's combined pre-dispatch question
task-list
TaskCreate / TaskUpdate / render the current TaskList in response to `/task-list` (with or without flags). The skill body executes immediately on the syntax — no permission-seeking, no echoing the list back as plain text.
sync
Sync files between two local directories, repos, or git worktrees. Five modes (plan/interactive/push/pull/mirror), .gitignore-aware, Claude-workflow allowlist via --claude, dropbox-restore-style per-directory prompts.
super
Brainstorming (alias for /brainstorming)