AGENT SKILL

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

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:

  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 old -> new — use the part after -> (the destination path).
    2. git branch --show-current.
    3. ls -t ~/.claude/projects/*/memory/*.md 2>/dev/null | head -1 → its name: frontmatter field; if none, the basename without .md.
    4. ls -t ~/.tesseract/shelf/*.md 2>/dev/null | head -1 → filename stem. Past-you's last anchor, recovered from the shelf itself.
    5. 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.

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.

04 同仓库更多 Skills

laurac8r
laurac8r/claude-damn

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.

前端开发视觉设计
★ 3
laurac8r
laurac8r/claude-damn

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

★ 3
laurac8r
laurac8r/claude-damn

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

★ 3
laurac8r
laurac8r/claude-damn

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.

★ 3
laurac8r
laurac8r/claude-damn

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.

★ 3
laurac8r
laurac8r/claude-damn

super

Brainstorming (alias for /brainstorming)

★ 3