Per-project scratchpad TUI plugin for OpenCode: capture and edit notes per project, stored privately outside your repo.
OpenCode sessions come and go, but every project accumulates little things worth keeping: a command you keep re-deriving, a decision and its rationale, the next step you don't want to lose. Context switching to an external notes app breaks your flow and scatters your notes across tools.
opencode-scratchpad gives each project one private scratchpad — a single free-form text document you can capture into and edit without leaving the TUI. It is not a list of notes or a task manager; it is one document per project, always in the same place.
- One scratchpad per project, keyed by the project's absolute path.
/scratchcommand/scratch <text>appends a line of text to the current project's scratchpad and shows a confirmation toast./scratch(no argument) opens the modal editor — on any terminal width.
- Modal editor — a command-palette-style dialog with an editable textarea, a key hint, and a saved indicator.
Enteradds a new line;Escsaves and closes. - Sidebar preview — the session sidebar shows an always-present collapsed Scratchpad dropdown. Click it to expand a read-only, truncated preview of the current notes; click again to collapse. It is never editable.
- Private and local — no network calls, no telemetry, and nothing written into your git repo.
- Plain Markdown on disk — one file per project, easy to back up, grep, or delete.
- OpenCode v2. Verified against OpenCode v2.0.27.
- The V2 TUI plugin API is currently beta. The plugin pins
@opencode/plugin@2.0.27, and you should pin versions too — the API may change between releases. - Runtime peers:
@opentui/core,@opentui/solid, andsolid-js(installed transitively by OpenCode).
OpenCode installs published plugins itself — do not npm install it into your project:
opencode plugin add opencode-scratchpadThat installs the package and adds it to your global config. To configure it by hand instead, add it to plugins in opencode.json(c) (V2 uses the plugins key); OpenCode installs any missing package at startup. See examples/opencode.json for a minimal config:
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["opencode-scratchpad"]
}Pin an exact version in production (e.g. opencode-scratchpad@0.2.0), since the V2 TUI plugin API is beta.
Because this package exports a server part (.) alongside its TUI part (./tui), opencode.json is the correct file — cli.json is only for packages with a TUI part and no server part.
To use a working copy, register it by absolute file:// path:
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["file:///absolute/path/to/opencode-scratchpad"]
}OpenCode loads the local directory through the tui.js and server.js entry forwarders shipped at the repository root. Restart OpenCode afterwards. When you install the published npm package by name instead, OpenCode resolves the ./tui and ./server package exports and the forwarders are not used.
/scratch Remember to regenerate the API client after schema changes
The line is appended to the current project's scratchpad and a toast confirms the write.
/scratch
The editor opens as a modal dialog styled like the command palette (Ctrl+P), on any terminal width. You can also run Scratchpad from the command palette (Ctrl+P).
| Key | Action |
|---|---|
Esc |
Save and close |
<leader>e |
Open the scratchpad in $VISUAL/$EDITOR |
Enter adds a new line, so multi-line notes stay easy to write. Your edits are written to disk when you close the editor. The <leader>e shortcut is a bindable command with id opencode-scratchpad.editor, configurable via keybinds in tui.json (e.g. "keybinds": { "opencode-scratchpad.editor": "<leader>e" }).
The session sidebar also carries an always-present Scratchpad row. Collapsed by default, it expands on click to a read-only preview of the current notes — the first ~10 lines, with an ellipsis when there is more. Click the row again to collapse it. The preview re-reads the file each time you expand it, so edits you make in the modal show up the next time you open it.
Sidebar visibility is host-controlled. The sidebar is shown by default only on wider terminals (more than 120 columns) and can be toggled on narrower ones. A plugin cannot force it visible; when it is hidden, the
/scratchmodal editor still works.
Everything is local. The plugin makes no network calls, collects no telemetry, and writes nothing into the git repo.
One Markdown file per project is stored at:
$OPENCODE_DATA_DIR/scratchpad/<projectKey>.md
OPENCODE_DATA_DIR defaults to ~/.local/share/opencode, so the default path is:
~/.local/share/opencode/scratchpad/<projectKey>.md
<projectKey> is a slug of the project directory basename plus an 8-char hash of the absolute directory path, which keeps same-named directories in different locations from colliding.
- Override the base directory with the
OPENCODE_DATA_DIRenvironment variable. - Notes are plaintext on disk. For sensitive notes, rely on OS-level disk encryption.
- Storage is keyed by absolute project path, so moving or renaming a project directory creates a new scratchpad rather than following the project.
The plugin reads options from the OpenCode plugin context (context.options):
| Option | Type | Default | Description |
|---|---|---|---|
dataDir |
string |
$OPENCODE_DATA_DIR (or ~/.local/share/opencode) |
Base data directory to store scratchpads under. |
ext |
string |
"md" |
File extension for scratchpad files. |
Pass options using the object form of a plugins entry (OpenCode reads them as context.options):
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
{
"package": "opencode-scratchpad",
"options": {
"dataDir": "/absolute/path/to/notes",
"ext": "md"
}
}
]
}dataDir must be an absolute path (the plugin does not expand ~). When dataDir is omitted, the OPENCODE_DATA_DIR environment variable is used if set, otherwise ~/.local/share/opencode.
bun install # install dependencies
bun test # run the test suite
bun run typecheck # type-check with tsc --noEmit- Search within the scratchpad.
- Timestamped captures.
- Optional per-project scratchpad templates.
- Configurable keybindings.
Issues and pull requests are welcome at https://github.com/adikpb/opencode-scratchpad. Please run bun test and bun run typecheck before opening a PR, and keep the scope focused on the single-scratchpad-per-project model.
MIT © 2026 adikpb