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