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