# Scratch > 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. - Skill: `nikiforovall/scratch` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add nikiforovall/scratch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nikiforovall/scratch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: NikiforovAll (https://skillmd.com/u/nikiforovall) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nikiforovall/scratch --- # 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 "" --dir _scratchpads [--id ] → creates // + scratchpad.json. 2. WRITE files into the pad dir with your normal tools (e.g. /notes.md). 3. REGISTER each file to track (group multi-doc pads with --group): scratch add "" --title "..." --desc "why it exists" \ --type note --tag a,b --group "Findings" 4. INSPECT: scratch ls # pads under root scratch ls "" # files in a pad scratch show "" scratch comments "" # inline comments left in the viewer # add --json to `ls`/`show `/`comments` for machine-readable output (agents) 5. BROWSE: scratch ui "" # 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 ` 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 "" --json` → `{ name, id, rel, files: [] }` - `scratch show "" --json` → `{ metadata, content }` (`metadata` null if unregistered) - `scratch comments "" [] --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. ## Addressing & roots Pads resolve by **name** (within a scanned root) or by **path**. Root order: `--dir ` → `$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 ""` reads them back (`--file ` 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 "" --rm [,...]` ## Cleanup - `scratch rm "" ` — unregister (file on disk is left untouched). - `scratch rm "" --force` — delete the whole pad directory. Pads persist until removed — nothing is auto-deleted.