Scratchpads

A scratchpad is an agent-authored MDX document. Instead of a wall of terminal text, an agent publishes something you can read at your own pace, edit, comment on, and hand back.

Where they live

.pragma/scratchpads/ in the worktree, git-excluded. The sidebar's Scratchpads card lists the selected worktree's documents; each opens as its own tab.

A scratchpad is two files: <name>.mdx (the document, with a managed frontmatter line Pragma maintains) and <name>.mdx.comments.json (the comment thread). Don't author scratchpad files by hand — the managed frontmatter is what makes the tooling work.

Reading and editing

The scratchpad tab has two modes sharing one buffer:

• Editor — rich markdown editing; MDX components render live in sandboxed iframes. Agents can ship interactive blocks (questions, diff reviews, progress) using the scratchpad UI components.
• Raw — CodeMirror with inline ⌘KCtrl+K AI edits, for tweaking the source directly.

If the file changes on disk (the agent updated it), a Changed on disk — reload button appears.

Built-in question choices, answers, diff decisions, and uncontrolled text fields are saved on this device, so they return when you reopen the scratchpad. They are separate from the scratchpad file and do not sync to other devices. Changing a component's source creates a new local state for that block; custom controlled components manage their own state.

Exporting HTML

Click Export HTML in either toolbar mode to export the current document, including unsaved edits, as one self-contained .html file. Pragma bundles the MDX and its imports with esbuild and embeds React, component styles, the current theme, static media, and literal whiteboard embeds. Open the file in a browser without running Pragma.

Exports are written to .pragma/scratchpads/exports/ in the document's worktree. Each export gets a unique filename, so earlier exports are preserved. The directory is git-excluded, and Finder (or your system file manager) opens after a local export. For SSH projects, the file is saved on the remote host.

Only the built-in actions that send text to agents are disabled: Send answer and diff-review Accept/Reject. Question choices and text fields remain interactive, as do custom buttons, tabs, and local React state. Pragma SDK host calls are replaced with disconnected no-op stubs, including direct SDK imports and SDK APIs re-exported by the scratchpad library; subscriptions yield no events.

Every exported file carries a Created with Pragma watermark linking to the Pragma homepage.

Diagrams

An agent can embed a whiteboard with <Whiteboard id="…" />: a live, theme-matched render of a durable Excalidraw board in the same worktree. Click it in the desktop app to open the interactive board in its own tab — editing happens there, not inside the document.

Commenting

Select a block and leave a comment. Comments collect in the thread; sending submits as one prompt to the attached agent — the agent re-reads the document and addresses each comment in order. If no agent is attached, Pragma offers a picker of the worktree's agent sessions.

Creating them

Agents create scratchpads from their own terminal:

pragma-cli scratchpad create --title "Architecture" result.mdx

The command writes the managed frontmatter, registers the document, and opens a scratchpad tab for you. When a fanout pick promotes a winner, the winner's scratchpads are promoted with it — the comparison's scratchpad columns stay with the work that survives.