scratch

name	scratch
description	Organize knowledge from an agent session into a scratchpad — a folder of files plus a scratchpad.json manifest. Use when a task generates notes, snippets, command output, diagrams, or artifacts worth keeping together for a session/activity.

scratch — session scratchpads

A scratchpad is a folder with a scratchpad.json manifest; the folder path is its identity (no central store). The CLI never authors, copies, or moves content — you write files with your normal tools, then register them for metadata + preview. Use it for session knowledge worth keeping together, not for the project's real source files.

scratch is on your PATH — run it directly. The skill's base dir is not where the CLI lives; don't look there for an entrypoint to invoke.

The loop

1. CREATE (default parent _scratchpads; create it if absent):
     scratch new "<name>" --dir _scratchpads [--id <session-id>]
   → creates <parent>/<slug>/ + scratchpad.json.

2. WRITE files into the pad dir with your normal tools (e.g. <slug>/notes.md).

3. REGISTER each file to track (group multi-doc pads with --group):
     scratch add "<name>" <file> --title "..." --desc "why it exists" \
       --type note --tag a,b --group "Findings"

4. INSPECT:  scratch ls           # pads under root
             scratch ls "<name>"  # files in a pad
             scratch show "<name>" <file>
             scratch comments "<name>"   # inline comments left in the viewer
             # add --json to `ls`/`show <file>`/`comments` for machine-readable output (agents)

5. BROWSE:   scratch ui "<name>"  # see viewer note — launch backgrounded

To extend an existing pad later, skip step 1 — ls to find it, write, add.

Scripting (--json)

ls and show <pad> <file> accept --json for parseable output (paths are relative, forward-slashed — never absolute, safe across shells/platforms):

• scratch ls --json → { root, pads: [{ name, rel, files }] }
• scratch ls "<name>" --json → { name, id, rel, files: [<entry>] }
• scratch show "<name>" <file> --json → { metadata, content } (metadata null if unregistered)
• scratch comments "<name>" [<file>] --json → { pad, comments: [...] } (see below)

Errors stay as text on stderr; stdout carries only the JSON, so pipe to jq freely.

Choosing a location (--dir)

Default to _scratchpads at the repo root unless the user names another parent (e.g. --dir _plans to co-locate with planning work). The same name under two parents = two distinct pads; an existing slug in one parent makes new refuse without --force.

Registering files (scratch add)

• --desc — why this file exists / what it captures. The most valuable field.
• --title — human label (defaults to path); --tag a,b,c — comma-separated.
• --type — note | snippet | output | artifact | reference (default note).
• --group — group header in the viewer; files sharing a name list together. Always set it once a pad holds more than ~3 files — it's the only structure the viewer shows. To set/change a group on existing entries, edit the group field in scratchpad.json in place — that's cheaper than re-running add per file and preserves the other metadata.

Write the file first, then add. Re-running add on the same path updates its metadata. add warns (doesn't fail) if the file is missing or outside the pad dir.

Group order (layout)

Groups list in first-appearance order by default. To control the order, add a top-level layout to scratchpad.json — an ordered list of groups (edit the file directly; there's no CLI flag):

"layout": { "groups": [{ "name": "plan" }, { "name": "research", "collapsed": true }, { "name": "" }] }

• Order follows the array. Names match the group field case-insensitively.
• Groups you omit sort after the listed ones (first-appearance order); the ungrouped bucket is { "name": "" } and sorts last unless you position it.
• "collapsed": true folds that group by default in the viewer.
• Applies to both the viewer sidebar and scratch ls. A layout entry with no matching files is skipped.

Addressing & roots

Pads resolve by name (within a scanned root) or by path. Root order: --dir <root> → $SCRATCH_DIR → current directory. ls/ui with no pad scan the root for all pads.

The viewer (scratch ui)

Read-only and blocking — keeps a local server alive until Ctrl+C. Always launch it backgrounded (don't await it) so the session keeps moving, then report the URL. Native glimpse window with automatic browser+server fallback (--browser forces it); shows all files in the pad (unregistered ones dimmed), renders markdown/code/mermaid, .excalidraw scenes, TeX math, GFM alerts (> [!TIP], uppercase), embeds HTML diagrams (below), raw↔rendered toggle, auto light/dark.

Diagrams (mermaid)

A fenced ```mermaid block renders to an SVG in the viewer (flowcharts, sequence, state, ER, gantt, class). Reach for it when the shape of a system is the point and you'd rather describe the relationship than draw it — it's the default for architecture, data-flow, and state diagrams in a note, and reads far better than an ASCII sketch. The viewer themes the diagram for light/dark automatically, so don't hardcode colors.

Before writing one, read references/MERMAID_GUIDE.md — it carries the label rules (line breaks, width budget, which characters need escaping). Skipping them is what makes a diagram come out unreadable.

When mermaid can't express it (bespoke layout, a chart, interactivity), embed an HTML diagram instead (below).

Call stacks

A fenced ```callstack block renders a hand-drawn tree of a code path, with what changed along it marked inline. Use it when the sequence of calls is the point — mermaid draws shape, a call stack draws a path.

Read references/CALLSTACK_GUIDE.md before writing one. The annotation rules fail silently when guessed.

Drawings (Excalidraw)

Add a .excalidraw file (scene JSON) like any other file — the viewer and exports render it to SVG; the scene stays editable in Excalidraw. Empty scene: {"type":"excalidraw","version":2,"elements":[],"appState":{},"files":{}}. To see a drawing, run scratch preview d.excalidraw and read the PNG path it prints.

Math notation (TeX)

Markdown docs may use TeX/LaTeX math — inline $…$ and display $$…$$ — rendered by KaTeX in the viewer. Reach for it when a note needs a real formula instead of prose or ASCII (e.g. $$\text{tokens} = \operatorname{round}(W/28) \times \operatorname{round}(H/28) + 2$$). No setup needed; just write the math in the doc.

Footnotes / citations

Markdown footnotes are supported — an inline [^id] reference plus a [^id]: … definition (Pandoc/GFM style). The viewer numbers each reference and renders a linked definitions list at the bottom. Use it for sources/citations in research notes (definitions render inline markdown, so links inside them work).

Embedding HTML diagrams

For anything markdown + mermaid can't express — a UI sketch, a custom chart, an interactive explainer — write a standalone .html file in the pad and embed it from a markdown doc with image syntax:

![Cache layout](diagram.html)

The viewer renders diagram.html live in a sandboxed iframe right where the embed sits. The .html is just a loose file next to the doc — resolved by its relative path, not something you scratch add. Keep the markdown as prose; let the diagram be its own file. The embed is self-contained (baked into the page), so it survives scratch export and offline viewing.

Write the file as a complete standalone HTML document (it then also opens in a plain browser). Scripts run isolated — no access to the viewer page. Every embed gets a built-in kit baked in (theme-aware CSS variables, pre-styled controls, SVG utility classes + an #arrow marker) so diagrams stay consistent and match the viewer's light/dark theme without hand-rolled CSS.

Before authoring one, always read references/HTML_DESIGN_GUIDE.md for the kit reference and the styling/structure contract.

Reading viewer feedback (scratch comments)

Reviewers attach inline comments to rendered text in the viewer — in a markdown preview, or in an .html file previewed as its own page. scratch comments "<name>" reads them back (--file <path|glob|substring> to narrow files; --json for agents) so you can act without opening the UI: each item gives the note, the quoted text, and the enclosing context block to edit (a markdown paragraph/list/quote, or the source element for an .html file). matched: false = the quoted text could not be found in the source (edited away, or generated at runtime by a script in an .html file); reconcile manually.

Comments are transient feedback — once you have acted on one, close the loop by deleting it: scratch comments "<name>" --rm <id>[,<id>...]

Cleanup

• scratch rm "<name>" <file> — unregister (file on disk is left untouched).
• scratch rm "<name>" --force — delete the whole pad directory.

Pads persist until removed — nothing is auto-deleted.