# Scratchpad App — Specification > Status: v1 scope settled; UI/visual spec done (`spec-visuals.md`); open questions resolved. ## 0. Guiding principle — thin layer over the filesystem **For the agent, a scratchpad is just a folder of files with a thin metadata layer on top.** The CLI does NOT mediate file content. Its job: 1. **Initialize** a scratchpad (create the folder + manifest at the right location). 2. **Emit a prompt** telling the agent how to work with the pad (where it is, conventions). 3. **Register** files the agent created into the manifest (with metadata). The agent then works *directly* on the filesystem — creates/edits files with its normal tools inside the pad dir — and uses the CLI only to init and to register/annotate files. Binary name: **`scratch`**. ## 1. Concept A **scratchpad** is a collection of files capturing *temporary knowledge* tied to an agent session or activity. The app lets you create scratchpads (named, or keyed by session id) and browse/preview them visually. Goal: organize ephemeral agent-generated knowledge, and (eventually) integrate it with other systems. Inspiration: - **glimpse** (hazat) — quick file preview feel. - **plannotator** (backnotprop) — borrow *layout*. - **~/dev/claude-code-hub** design system — borrow *styles* (DEFERRED until later). ## 2. Core mental model (decided) - **Storage = directory + manifest.** Each scratchpad is a folder (named by session id or a human label) containing arbitrary files (.md, code snippets, images, JSON dumps) **plus a manifest** (e.g. `scratchpad.json`) holding metadata: title, session id, tags, created/updated timestamps, file list. - **Producer = agents primarily.** Claude Code / agent sessions write scratchpad files automatically (via hooks/tools). Humans mostly view; light curation later. - **Viewer = browse + preview.** List scratchpads → click one → preview its files: markdown rendered, code highlighted, images shown. glimpse-style quick look. Annotation is NOT a v1 requirement. ## 3. Interface = CLI-first, optional UI (decided) The primary interface is a **CLI**. It is the single surface both humans and agents use. A **skill** will later wrap the CLI so agents invoke it naturally during sessions. The CLI launches an **optional web UI** (browse + preview) on demand. ### CLI capabilities (initial) - Create a scratchpad. - Add a file to a scratchpad. - List what's in a scratchpad (and list scratchpads). - Attach optional **meta info** about a scratchpad file. - Open the UI. - `[?]` **Query** a scratchpad — flagged as a "dig deeper" idea (search/grep across files? semantic query? filter by metadata?). Usefulness TBD. ### Location & addressing (decided — no central store) **A scratchpad is just a folder containing `scratchpad.json`. The folder path is its identity. The tool assumes NO central store** (`./_scratchpads` is not baked in). - **Creation requires an explicit location.** `scratch new --dir ` creates `//`. With no `--dir`, the command errors — placement is always deliberate. The agent/skill *suggests* a location (e.g. `_plans/` or `_scratchpads/`) but the tool never assumes one. - **Discovery = scan a root.** `ls` / `add` / `show` / `ui` operate on a **root dir** (default = cwd; override with `--dir` or `SCRATCH_DIR`) and find pads by scanning for `scratchpad.json`. A pad is referenced by name (resolved within the scanned root) or by path. - **Name collisions are fine across different dirs** — identity is the path, so two pads may share a name in different locations. Within the *same* parent dir, an existing slug = an existing pad → `new` refuses (use `--force` to adopt/overwrite-manifest). - Co-locating pads under `_plans/` is a first-class use (a scratchpad and a planning task folder are the same kind of artifact). ## 4. Tech & decisions (decided) - **Stack: Bun/Node + web UI.** Single TS codebase. CLI in Bun/Node; `scratch ui` renders an HTML UI for browse+preview. **Transport = glimpse native WebView** (`glimpseui`), not a browser tab (see spec-visuals §2; browser+local-server kept as a fallback). Web design refs (glimpse/plannotator/claude-code-hub) drop straight in. - **Identity: the folder path.** Addressed by path, or by name resolved within a scanned root (see §3). An optional `id` (e.g. session id) is stored in the manifest only. - **Query: deferred to v2.** v1 = create / add / list / open. Design query once real scratchpads exist. - **Lifecycle: kept, manual cleanup.** Never auto-delete. Provide `rm`/`prune` commands. ## 5. CLI command surface (decided) **Style: noun-less flat verbs. Stateless — pad always named explicitly (no "active" pad).** **Pad referenced by name (resolved within the root) or by path. Root = cwd, or `--dir` / `SCRATCH_DIR`.** ``` scratch new --dir [--id ] # create // + manifest, # then PRINT a prompt: where the pad is + how to use it # (--dir REQUIRED — no assumed location) scratch add [--title .. --desc .. --tag t1,t2 --type note] # register an ALREADY-PRESENT file into the manifest scratch ls [--dir ] # list pads found under root (scan for scratchpad.json) scratch ls # list files in a pad scratch show [] # print metadata / file content scratch rm [] # manual cleanup scratch ui [] [--dir ] # UI (glimpse window; browser fallback) over root/pad ``` **`add` = create-in-place + register.** The agent writes the file into the pad dir using its own tools, then calls `add` to record it in the manifest with metadata. The CLI does not copy, move, or author content — it only registers and annotates. (Reasonable to also let `add` warn if the file isn't under the pad dir.) **`new` output is a prompt, not just a confirmation** — it tells the agent the absolute pad path, the manifest location, and the recommended workflow (write files here, then `scratch add` to register). This is the agent's onboarding into the pad. ## 6. Manifest schema (decided fields) Per scratchpad (`//scratchpad.json`): - `name`, `id` (optional), `created`, `updated`, `files[]`. Per file entry: - `path`, **`title`**, **`description`** (why it exists), **`tags[]`**, **`type/role`** (note / snippet / output / artifact / reference). - Provenance (source tool/command/url) — **excluded from v1**, candidate for later. ### Concrete `scratchpad.json` shape (decided) ```json { "version": 1, "name": "auth refactor", "id": "abc123session", "created": "2026-06-07T10:00:00Z", "updated": "2026-06-07T11:30:00Z", "files": [ { "path": "notes.md", "title": "Auth flow notes", "description": "Why the token refresh races", "tags": ["bug", "auth"], "type": "note" } ] } ``` - `version` — schema version, lets the format evolve. - `path` — **relative to the pad dir** (pad stays portable). - Timestamps — ISO-8601 UTC. - `type` — enum: `note | snippet | output | artifact | reference` (default `note`). - Unknown/extra keys tolerated on read (forward-compatible). ### Slug & collision rules (decided) - Folder name = **slug of `name`** (lowercase, spaces/punct → `-`, trim repeats). `"Auth Refactor!"` → `auth-refactor`. - `--id` is stored in the manifest only; it does **not** change the folder name. - **Collision is scoped to one parent dir.** Two pads may share a name in *different* `--dir` parents (path = identity). Within the *same* parent: if `/` already exists, `new` **refuses** with a clear error; `--force` adopts/overwrites the manifest. No silent suffixing — predictable folder names. ## 7. UI Browse + preview. **Full visual spec → `spec-visuals.md`.** Summary: - Transport: **glimpse native WebView** (browser+server fallback). - Layout: **2-pane** — collapsible pad/file tree (left) + preview (right). - Style: **claude-code-hub "Lab Notebook"** tokens; **dark + light toggle** in v1. - **Pure viewer** — plannotator's annotation / Ask-AI / feedback model deliberately dropped. Not a v1 blocker for the CLI, but in scope for v1 success criterion #2. ## 8. v1 success criteria (decided — all required) 1. **Full CLI loop works** — `new --dir / add / ls / show / rm` operate over a folder+manifest under an explicit/scanned root, with a valid manifest. Verified by tests. 2. **UI renders a pad** — `scratch ui` opens (glimpse window or browser fallback), lists pads, previews a pad's markdown / code / images. 3. **Agent skill wired** — a skill lets Claude Code agents init + populate scratchpads via the `scratch` CLI in a real session. 4. **Installable binary** — `scratch` runs globally on the machine (bun/npm bin or compiled). ## 9. Remaining design work (post-spec) - `query` command — v2 (search across files + metadata). - Provenance metadata — later. - `[?]` Whether `scratch ls` scans the root recursively or one level deep (lean: recursive, but skip nested pads inside a pad). Decide in build.