Docket

One list every AI tool you use can write to — Claude Code, Codex, Cursor, Warp — across every project, before the work is worth a ticket. Local-first, self-hostable, no SaaS account.

A thought that shows up mid-session is worth capturing but not worth the ceremony: a Notion template, a GitLab issue format, a ticket id you have to invent. So today it evaporates. Docket is the layer underneath all of that — work lands here at the speed an agent can type, from any tool, in any project, and graduates to Notion/GitLab/Obsidian when it's earned it.

Nobody else occupies this space, and it isn't an accident: Anthropic will not integrate Claude Code with Cursor, and Cursor will not integrate with Codex. Every vendor optimises its own closed loop. The space between the tools is structurally nobody's.

One list, many projects

Docket files every item under the project it was captured in, automatically — resolved from the git remote of wherever the agent is running. You never type it, and no agent has to remember to.

~/work/backend      claude-code, codex   ─┐
~/side/tracker      claude-code          ─┼──▶  docket  ──▶  one list, three scopes
~/side/notes        codex, warp          ─┘

• todo_list in ~/work/backend shows that project's open items, not all three projects' — compact, one line each.
• The web dashboard has a workspace switcher with per-project open counts.
• Items with no project context land under Unfiled and stay visible, never guessed at.

Using the git remote rather than the path means the same repo cloned to ~/src/backend on a laptop and /work/backend on a desktop is one workspace — which matters precisely because sync exists. Full resolution order and the .docket.json override: docs/workspaces.md.

_{Regenerate these with node docs/assets/demo-seed.mjs — it builds the workspace they show, so they stay a picture of the real dashboard rather than a staged one.}

Quick start

You need: Claude Code (or another MCP host) and Node.js 18+ (node --version; get it from nodejs.org).

npx -y @pasichdev/docket setup          # one shared data dir, detected MCP hosts configured
claude mcp add docket -- npx -y @pasichdev/docket

Restart Claude Code and ask it "add a todo: buy milk". The web dashboard is at http://localhost:8787 — it started itself the moment the first client connected.

Optionally, to see what's open in a project when a session starts:

npm install -g @pasichdev/docket        # the hook runs a command, so it needs one on PATH
docket hook install                     # then: docket hook doctor

hook install works without the global install too — it pins the command to this exact copy of docket and tells you it did — but the short form survives moving or reinstalling, and npx leaves nothing on PATH.

Using Claude Desktop, Cursor, Windsurf, Zed, or Warp instead? Same MCP config shape — see Supported hosts.

Upgrading from 2.x

Read this before you upgrade if you have existing items.

3.0 migrates your store from data format v7 to v8 on first run, automatically. The migration itself is safe and is not the risk. Downgrading afterwards is.

docket 2.3.1 writes the store from its own v7 shape: it has never heard of the fields v8 adds, so its very first write after a reinstall silently strips them from every item. Nothing errors, and a later re-upgrade hands out fresh sequence numbers that no longer mean what your paired devices think they mean. 2.3.1 is published and cannot be patched, so 3.0 defends the only way it can — by keeping a copy of your pre-migration store:

~/.docket/todos.v7-pre-upgrade.enc

It is written once, before the first v8 write, and never overwritten. The upgrade prints its path on the run that creates it.

To go back to 2.x, restore it first:

docket restore --from-v7                     # puts the v7 store back; moves the v8 one aside
npm install -g @pasichdev/docket@2.3.1

In that order. restore --from-v7 deletes nothing — your v8 store is renamed aside, so you can come forward again later.

If you would rather have a portable copy as well, docket backup ./pre-v3.backup before upgrading gives you one that includes your identity and paired peers.

Bridges, not replaces

Docket is deliberately not where work lives forever. It's where work lands first, before anyone knows whether it deserves a ticket. Most of it doesn't and gets closed by hand; the rest graduates.

sourceUrl is the bridge in both directions. Set it whenever an item maps to something with a URL — a GitLab issue, a Notion page, an Obsidian share link, a Slack thread, a GitHub PR — and the card carries a clickable link straight back to it.

Why not just use GitHub Issues? Because an issue costs a title you have to phrase for an audience, a repo you have to pick, and labels you have to maintain — and because your Cursor session can't write one for you while you're mid-thought in a different project. Docket costs one sentence, from whichever tool you already have open. When the item turns out to matter, it becomes an issue, and sourceUrl remembers where it went.

Supported hosts

Any MCP host works — the tools are identical everywhere:

{
  "mcpServers": {
    "docket": { "command": "npx", "args": ["-y", "@pasichdev/docket"] }
  }
}

{
  "context_servers": {
    "docket": { "command": { "env": {}, "path": "npx", "args": ["-y", "@pasichdev/docket"] } }
  }
}

The one hook

Claude Code additionally gets a SessionStart hook, and only that one:

docket hook install      # writes .claude/settings.json (--global for user-wide)
docket hook doctor       # proves it fires, and reports measured latency
docket hook uninstall    # removes only the entries docket owns

When a session starts it injects the items open in that project — compact, at most 7, under 120 tokens. Nothing at all when the project has nothing open. Its whole job is continuity: you come back to a terminal and the thread is already there.

Don't want it? export DOCKET_HOOKS=off disables it immediately, without editing any config or uninstalling anything. docket hook doctor measures the real round trip and says so if it is slow enough to notice.

It fails open, always. Server not running, request timed out, malformed response, DOCKET_HOOKS=off — every one of those exits 0 and prints nothing. A tool that degrades your session when the tool itself is broken gets uninstalled, at which point it helps nobody. docket hook doctor runs the configured command for real and reports what a session would actually see, so a hook that never fires is visible rather than merely silent.

No PreToolUse, no blocking, no other hosts — the hook's only job in this release is continuity, not enforcement.

Guidance for non-Claude-Code agents

The tools work everywhere; the guidance ships as a Claude Code plugin. For any other agent, copy skills/docket/SKILL.md (everything below the --- frontmatter) into whichever file your agent reads — AGENTS.md for Codex, .cursor/rules/docket.mdc for Cursor, .windsurfrules for Windsurf, CLAUDE.md for Claude Desktop, or Warp's custom-instructions setting.

/plugin marketplace add pasichDev/docket
/plugin install docket@docket

Tools