A scratchpad for Claude Code. Halfway through a prompt, something else comes to mind: open the pane, note it, close the pane, and your prompt is back as you left it. Later, pull the note into the prompt when you get to it. Claude can jot notes for you too.

In the demo: note something mid-prompt, then add a saved note to the prompt.

Notes are kept per project, and the pane shows all of them. Syncing between machines and a phone app are optional.

What it does

• Capture a note in under two seconds, even while Claude is working. Mid-prompt, ctrl+x s opens the pane and ctrl+n starts a note; close the pane and your draft is back. In an empty prompt, /jot text or // saves one without opening anything.
• Gives Claude a jot tool: Claude jots notes it thinks are important or wants to pass on to you. You can also ask it to add one: "jot that down". Claude can also list your notes and archive one once it's done.
• Triage open notes across all your projects in a searchable pane: edit, move, archive, bundle several into one prompt.
• Dispatch a note into the prompt. This project's open notes sit in a row of numbered chips above the prompt (the "pocket"); type ; and a note's number (;2) in an empty prompt to pull it in. A lone number is left alone, so it still answers Claude's numbered questions. Mid-prompt, find the note in the pane and press t: it goes in under what you've typed.
• Harvest (opt-in): after each turn, an extra review looks for side issues that came up and offers them as notes, which you keep or dismiss. It doesn't change what Claude is doing.
• Sync: two-way sync enabled by multiple methods. Through a small hub, a plain folder, Obsidian or a combination of methods (Sync).
• Desktop: save a note from a key on your desktop, or from a script, without opening Claude Code: ostrakon jot (Notes from the desktop).
• Phone: capture and triage from your phone with the hub's web app, installed to the Home Screen, or send a note from the share sheet or Siri with an iOS Shortcut.

Notes are plain Markdown files with some YAML. One per note, in ~/.local/share/ostrakon/ by default, so they are yours to read, grep and back up.

Sync

Sync is optional and works both ways. Add, edit, move or archive a note on one machine or on your phone, and the change shows up everywhere else. If the same note changes in two places, the later change wins everywhere. There are a few ways to sync; use one or combine them:

• The hub (server/): a small service you run on one of your machines. Your other machines and your phone reach it over Tailscale (the easy option) or your own HTTPS proxy, tunnel or VPN. Changes show up in other sessions within seconds, and the hub also serves the phone app. Setup: the hub and the phone app.
• A folder (the mirrorDir option): ostrakon keeps a copy of your notes in a folder, and whatever syncs that folder (Dropbox, Syncthing, any synced drive) carries them between machines. Point it at an Obsidian vault and you can edit notes there too; your edits come back. Obsidian shows each note's metadata as Properties at the top; to hide them, set Settings → Editor → Properties in document to Hidden. No server needed.
• Both at once: they work independently, so you can use the hub for your phone and a folder for Obsidian.

On your phone, the hub's web app installs to the Home Screen and opens straight to a note field. You can triage there too (edit, move, archive, mark sent), and anything you capture offline is kept until the hub is reachable again. To pair a phone, scan the QR code that ostrakon pair shows. An iOS Shortcut can send a note from the share sheet or Siri without opening the app. Details: docs/phone.md.

Install

There are two ways to install it:

• The install script gets you the mod and the ostrakon command: jot, update, doctor, pair, and the hub for syncing and the phone app. Updates come through ostrakon update.
• Claude Code's plugin marketplace gets you the mod only. There's no ostrakon command, so you can't run the hub or pair a phone from it; folder sync, and a hub set up on another machine, still work. Updates come through Claude Code.

Use one or the other. The install script offers to add the keybindings; with the marketplace, add them yourself.

Requirements

• Claude Code with mods support (see the mods docs). Tested with 2.1.310; mods are still changing, so a much older or newer version may not work.
• git, and python3 for the install script (without it, the script tells you the one line to add yourself).
• For the hub: Bun (tested with 1.4.4) to run the hub and to use ostrakon pair and ostrakon jot, and qrencode for the pairing QR code. install.sh --hub sets the hub up as a systemd service, so that part is Linux-only for now; elsewhere, run ostrakon hub however you like to keep things running.

Tested on Linux. macOS should work for the mod but hasn't been tried yet; reports are welcome.

With the install script

One command clones ostrakon into ~/.local/share/ostrakon-src and installs the newest release:

curl -fsSL https://raw.githubusercontent.com/gaius-codius/ostrakon/main/get.sh | bash

Add -s -- --hub after bash to set up the hub too, or -s -- --main to follow the newest code on main instead of releases. Running it again updates what's there. To read the script before running it: curl -fsSL https://raw.githubusercontent.com/gaius-codius/ostrakon/main/get.sh -o get.sh, look it over, then bash get.sh.

Or clone the repo wherever you like and run the install script yourself:

git clone https://github.com/gaius-codius/ostrakon.git
cd ostrakon && ./install.sh --release

Either way, the install script:

• switches to the newest release (leave out --release to run what's on main),
• loads the mod in every Claude Code session, by setting CLAUDE_CODE_PLUGIN_DIRS in ~/.claude/settings.json (only if it isn't set already, and it keeps a .bak copy),
• and adds the ostrakon command to ~/.local/bin.

It's safe to run again. ./install.sh --hub also sets up the hub (below).

To try it without installing anything, load it for a single session: claude --plugin-dir ostrakon/plugin. To install by hand, add the folder to ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/ostrakon/plugin" } }

From the plugin marketplace

claude plugin marketplace add gaius-codius/ostrakon
claude plugin install ostrakon@ostrakon

Update it with claude plugin update ostrakon@ostrakon, or turn on auto-update for the marketplace in /plugin. A new copy arrives with each release. If you also run the install script, it sees the plugin and doesn't load the mod a second time.

Updating

ostrakon update             # or ./update.sh in the repo
ostrakon update --main      # switch to the newest code on main instead of releases
ostrakon update --release   # switch back to releases
ostrakon version

If you installed a release, update moves you to the newest one; if you're on a branch, it pulls that branch (and stops rather than touch commits of your own). It restarts the hub if it's running here, after new code or when the hub still runs an older release, and lists what changed. Restart any open Claude Code sessions to pick up the new version. Each release's changes are in CHANGELOG.md.

If something isn't working

ostrakon doctor

It checks that the mod loads, which Claude Code version last ran it and whether anything went wrong there, your notes folder, the hub and its token, and the tools ostrakon needs, and says what to fix. It changes nothing and never prints your token, so its output is safe to paste into a bug report.

Keybindings

A mod can't add keyboard shortcuts of its own, so ostrakon borrows some existing Claude Code actions (which is why the names below look unrelated). The install script asks whether to add these to ~/.claude/keybindings.json (--keys adds them without asking, --no-keys skips them). It leaves alone any key you've bound to something else, and any of these actions you've already given a key. To add them by hand:

{
  "bindings": [
    { "context": "Chat", "bindings": { "ctrl+x s": "app:cycleDiffBase", "ctrl+x tab": "app:openArtifact" } },
    {
      "context": "Pane",
      "bindings": {
        "ctrl+x s": "app:cycleDiffBase", "ctrl+x tab": "app:openArtifact", "ctrl+q": "pane:previous",
        "ctrl+f": "app:toggleDiffNoiseFilter", "ctrl+s": "app:toggleDiffPreSession", "ctrl+n": "pane:next",
        "ctrl+x i": "app:toggleReplTab"
      }
    },
    {
      "context": "PaneField",
      "bindings": {
        "ctrl+x s": "app:cycleDiffBase", "ctrl+x tab": "app:openArtifact", "ctrl+q": "pane:previous",
        "ctrl+f": "app:toggleDiffNoiseFilter", "ctrl+s": "app:toggleDiffPreSession", "ctrl+n": "pane:next",
        "ctrl+x i": "app:toggleReplTab"
      }
    }
  ]
}

ctrl+x s opens and closes the pane, and ctrl+x tab moves the keyboard between the pane and the prompt, leaving the pane open (it takes the place of Claude Code's ctrl+x tab, which focuses the band above the prompt; a click still does). The other keys work inside the pane. /jot and // need no setup. The full key list is in docs/SPEC.md §4.

Configuration

Set these under the plugin's options (pluginConfigs.ostrakon.options in your settings, or pluginConfigs["ostrakon@ostrakon"].options if you installed it with claude plugin install):

Option	Default	What it does
notesDir	~/.local/share/ostrakon	Where notes are stored. The OSTRAKON_DIR environment variable overrides it.
pocket / pocketMax	on / 5	The numbered chips above the prompt, and how many show.
harvest	off	Review each finished turn for side issues worth keeping.
harvestMode	fork	fork reviews the whole conversation, tool output included, so it sees more but costs more as the conversation grows. light has a small model read only your prompt and Claude's final answer: much cheaper, but it misses more.
harvestMaxPerTurn	3	The most notes harvest offers after one turn.
hubUrl / hubToken	empty	The hub to sync with, and its token. Empty: no hub.
mirrorDir	empty	A folder to keep a synced copy of your notes in, such as a Dropbox or Syncthing folder or part of an Obsidian vault.

The hub and the phone app (optional)

The hub is a single Bun file (server/hub.ts) that stores notes in SQLite. It only listens on the machine it runs on and needs a token for every request, so you choose how other devices reach it. We use Tailscale, the simplest option: tailscale serve gives it an HTTPS address only your devices can reach, and install.sh and ostrakon pair set it up for you.

./install.sh --hub

This creates a token in ~/.config/ostrakon-hub/env (if there isn't one yet) and installs and starts the hub as a systemd user service (server/ostrakon-hub.service). It then prints the two steps left for you: loginctl enable-linger, so the hub keeps running when you log out, and tailscale serve, to put it on your tailnet.

To pair a phone, run ostrakon pair (it needs qrencode) and scan the QR code. The code in it works once and expires after 5 minutes, so the QR never contains the token itself; --token prints a link that does.

To run the hub in the foreground instead: HUB_TOKEN=$(openssl rand -hex 24) ostrakon hub. The ostrakon command reads HUB_TOKEN from the environment or from ~/.config/ostrakon-hub/env.

Not using Tailscale? Any HTTPS reverse proxy, tunnel or VPN works too; see Open it.

The service runs ~/.local/bin/ostrakon hub, so it doesn't matter where the repo lives. Phone setup, the Home Screen app and the iOS Shortcut are covered in docs/phone.md. Read SECURITY.md before making the hub reachable from other devices.

Notes from the desktop

Save a note without opening Claude Code. Needs Bun.

ostrakon jot call the plumber
ostrakon jot -p cc fix the flaky test     # file it under a project

• Where it goes: this machine's notes folder, so it shows in your sessions here. If the mod has a hub set, the note goes to the hub at once and reaches your phone and other machines within seconds.
• Hub down? The note stays here, and a session sends it to the hub later.
• --project / -p takes a project your notes already know, by name or key.
• No mod on this machine? Set OSTRAKON_HUB_URL and OSTRAKON_HUB_TOKEN. If either is set, both are read from the environment.

A quick-note key

ostrakon jot --ask opens a one-line prompt, saves what you type and shows a notification. Start the line with @name to file it under a project: @cc fix the flaky test.

Bind ~/.local/bin/ostrakon jot --ask to a key in your desktop's keyboard settings or your window manager's config. On Hyprland, in bindings.conf:

bindd = SUPER SHIFT, J, Ostrakon note, exec, ~/.local/bin/ostrakon jot --ask

On Omarchy, in ~/.config/hypr/bindings.lua:

o.bind("SUPER + SHIFT + J", "Ostrakon note", "~/.local/bin/ostrakon jot --ask")

The prompt comes from a tool you likely have already: walker, fuzzel, rofi, wofi or zenity. On Omarchy it uses Omarchy's own prompt. On macOS it uses osascript, which is untested so far.

From other apps

A Slack bot, a script or another machine can post to the hub's /api/jot with a source. The note is yours, and the source is kept as where it came from. See docs/phone.md.

Known limitations

These come from Claude Code's mods interface, which is still new, and should go away as it matures.

• Long notes in the pane's text field. When a note is longer than the capture or edit field, the text doesn't scroll with you: it disappears past the end of the field, while the cursor keeps moving and can even drop to an empty "second" line. What you type is all there, though, and the whole note shows in full just below the field as you write. It needs a text field that wraps or scrolls, which mods don't have yet.
• Claude Code updates can break things. Mods change between versions. If something stops working after an update, run ostrakon doctor and mention your Claude Code version when you report it.

More, including a couple of folder-sync edge cases, in ROADMAP.md.

Development

• How it's designed, and notes on the platform it builds on: docs/SPEC.md. How it looks: docs/DESIGN.md. Ideas for what's next: ROADMAP.md.
• tools/check.sh runs every check: claude plugin validate, the design check (docs/DESIGN.md against the code), the type-check, claude plugin test and the hub's tests. The mod's tests and type-check need the claude CLI installed, because the mods test kit and types ship with it. CI runs the tests on the version bin/tested-with names.
• The hub's tests need only Bun: cd server && bun test.
• How to contribute, and how releases are made: CONTRIBUTING.md.
• tools/ also has the screenshot pipeline and some experiment scripts; they write to working-docs/, which git ignores.

License

MIT