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

```json
"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.

## Related pads (`related`)

When one pad depends on another (one reads the other's decisions, ids or notes), link them with a top-level `related` list in `scratchpad.json` (edit the file directly; there is no CLI flag):

```json
"related": ["client-sdk", { "pad": "../other/pad", "rel": "feeds" }]
```

- An entry is a pad name or a path. A name resolves among the pad's sibling folders first, then under the root. A path is relative to the pad's folder.
- `rel` is an optional short label, shown on the pad's header in the viewer.
- Put the link in ONE pad. `scratch ui <pad>` and `scratch export <pad>` then cover the set: the pad, the pads it lists, and the pads that list it. One level only, each pad once. A name that does not resolve prints a warning and is skipped.
- In the viewer each pad gets its own sidebar section with its own groups, `layout` order and folding. A markdown link to a file registered in another pad of the set (`[Auth](../api-design/notes.md#auth)`) opens that file and moves the sidebar to that pad.
- `scratch comments <pad> --related` reads comments from every pad in the set; each item carries `pad`.
- Files stay in their own pad. Cite across pads by relative link, not by copying.

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

```md
![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>...]`

For a pad with related pads, add `--related` to read (or `--rm`) across the whole set.

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

• SKILL.md 10 KB
• references/CALLSTACK_GUIDE.md 2 KB
• references/HTML_DESIGN_GUIDE.md 8 KB
• references/MERMAID_GUIDE.md 3 KB