{
"markdown": "# Docket\n\n[](https://www.npmjs.com/package/@pasichdev/docket)\n[](https://github.com/pasichDev/docket/actions/workflows/ci.yml)\n[](https://registry.modelcontextprotocol.io)\n[](LICENSE)\n\n**One shared workspace for your AI coding agents. Local-first and\nself-hostable.** Claude Code, Claude Desktop, Cursor, Windsurf, Warp, Codex —\nadd an item in one, see it in all of them, plus a real-time web dashboard and\nyour phone. Nothing gets lost switching tools or starting a new session.\n\nDocket talks to every one of those tools over [MCP](https://modelcontextprotocol.io)\n(Model Context Protocol) — that's the integration mechanism, not the product.\nThe product is one shared workspace: what's claimed, what's done, who did it,\nand when. **Run it entirely on this machine, or self-host it on infrastructure\nyou control — no SaaS account either way.**\n\n**What it adds beyond \"just a list\":**\n\n- **Local or self-hosted** — keep everything on this machine, or run one\n always-on Docket Server and point every device at it (see\n [Deployment modes](#deployment-modes)).\n- **See who's doing what.** Claim an item before starting on it — other\n sessions see it's taken instead of duplicating the work; atomic (`409` on a\n race) in Self-hosted Mode.\n- **Full history** — every create/edit/claim/complete is logged with who and\n when.\n- **Todo vs. backlog** — keep near-term work separate from things you want to\n park without losing them.\n- **Private by default** — the data file is encrypted on disk (see\n [Security](#security)).\n- **Real-time Web UI** — light/dark theme, search, sort, inline edit, and a\n Viewer Gate for opening it from your phone.\n- **Optional multi-device P2P sync**, entirely separate from Self-hosted Mode\n — see [Devices & P2P sync](#devices--p2p-sync).\n\n
\n \n \n
\n\n## Architecture\n\nDocket runs in one of two deployment modes. Both give every client the exact\nsame MCP tools and Web UI; only *where the authoritative state lives*\ndiffers.\n\n**Local Mode** (the default — nothing here requires any setup beyond\n[Quick start](#quick-start)):\n\n```text\nClaude · Codex · Cursor · Windsurf · Warp\n │\n MCP\n │\n Docket\n │\n encrypted state\n (this machine, ~/.docket)\n```\n\n**Self-hosted Mode** (opt-in):\n\n```text\nClaude / Codex / Cursor\n │\n stdio MCP\n │\n local Docket client\n │\n authenticated remote transport\n │\n Docket Server\n (an always-on machine you control)\n │\n authoritative state\n```\n\nThe Docket Server is authoritative — **not** another P2P replica. Every\nclient becomes a thin, authenticated forwarder to it; there's no local\nwritable copy in this mode. A third, independent topology —\n[P2P sync](#devices--p2p-sync) — replicates a full copy onto each of your own\npaired devices instead; see [Deployment modes](#deployment-modes) for how all\nthree fit together.\n\n## Deployment modes\n\n| | Local Mode | Self-hosted Mode |\n|---|---|---|\n| **Default?** | Yes — zero config | Opt-in |\n| **Where state lives** | This machine (`~/.docket`) | The Docket Server you run |\n| **Setup** | `docket setup` | `docket setup`, choose \"Self-hosted\", or `docket pair ` |\n| **Web UI** | Runs on this machine | Served by the Docket Server |\n| **Multi-machine** | Optional [P2P sync](#devices--p2p-sync) between your own devices | Every paired device talks to one server |\n| **Good for** | A single machine, or a few you personally use | An always-on Raspberry Pi, mini PC, NAS, home server, or VPS |\n| **If the connection drops** | N/A | Every read/write/claim fails clearly — never a silent local fallback |\n\nBoth modes install from the same package and expose the same MCP tools — the\ndifference is entirely in `docket`'s configuration, not in what your AI agent\ncan do. Full self-hosted setup, CLI, and what it deliberately doesn't do\n(offline writes, combining with P2P sync, automatic conflict merge, hosted\naccounts): **[`docs/self-hosting.md`](docs/self-hosting.md)**.\n\n## Quick start\n\nFive minutes, no prior MCP experience needed. This is the **Local Mode**\npath — the simplest default. Want an always-on shared workspace instead? See\n[`docs/self-hosting.md`](docs/self-hosting.md).\n\n**You need:** [Claude Code](https://claude.com/claude-code) (or another MCP host) already\ninstalled, and Node.js 18+ (`node --version`; get it from [nodejs.org](https://nodejs.org) if missing).\n\n**1. Run the interactive setup wizard.** Creates and verifies one shared data\ndirectory, configures detected MCP hosts, optionally installs the claim\nskill:\n\n```sh\nnpx -y @pasichdev/docket setup\n```\n\n**2. Register the server.**\n\n```sh\nclaude mcp add docket -- npx -y @pasichdev/docket\n```\n\n**3. Restart Claude Code**, then **try it** — ask Claude *\"add a todo: buy\nmilk\"*. If it uses the tool and confirms, you're set.\n\n**4. Open the web UI** at **http://localhost:8787** — it started itself the\nmoment step 3 ran.\n\n**5. (Optional) Install the claim-tracking skill** — teaches Claude Code to\nmark items in progress and check before duplicating work:\n\n```sh\n/plugin marketplace add pasichDev/docket\n/plugin install docket-claim@docket\n```\n\nUsing Claude Desktop, Cursor, Windsurf, Zed, or Warp instead? See\n[MCP integrations](#mcp-integrations) below.\n\n## MCP integrations\n\nAdd to your host's MCP config — same `command`/`args` shape everywhere:\n\n```json\n{\n \"mcpServers\": {\n \"docket\": { \"command\": \"npx\", \"args\": [\"-y\", \"@pasichdev/docket\"] }\n }\n}\n```\n\n| Host | Config file |\n|---|---|\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) |\n| Cursor | `.cursor/mcp.json` or Global MCP settings |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| Zed | `~/.config/zed/settings.json` — uses `context_servers`, see below |\n\n\nZed's config shape is slightly different\n\n```json\n{\n \"context_servers\": {\n \"docket\": { \"command\": { \"env\": {}, \"path\": \"npx\", \"args\": [\"-y\", \"@pasichdev/docket\"] } }\n }\n}\n```\n\n\nAny of these hosts can also point at a **self-hosted** Docket — pair the\ndevice first (`docket pair ` or `docket setup --remote `), then\nregister the server exactly as above; nothing about the MCP host config\nitself changes.\n\n**From source:**\n\n```sh\ngit clone https://github.com/pasichDev/docket.git && cd docket\nnpm install && npm run build\nclaude mcp add docket -- node \"$(pwd)/dist/index.js\"\n```\n\n**Non-Claude-Code agents** (Codex, Cursor, Windsurf, Warp, ...): the MCP\ntools work identically everywhere; the claim-workflow *guidance* ships as an\ninstallable plugin for Claude Code only — for every other agent, copy\n[`skills/docket-claim/SKILL.md`](skills/docket-claim/SKILL.md) (everything\nbelow the `---` frontmatter) into whichever file your agent reads\n(`AGENTS.md` for Codex, `.cursor/rules/docket.mdc` for Cursor,\n`.windsurfrules` for Windsurf, `CLAUDE.md` for Claude Desktop/web, or Warp's\ncustom-instructions setting).\n\n## CLI\n\n```text\ndocket list | stats | export | import Workspace inspection\ndocket serve | pair | devices | status Self-hosted server & devices\ndocket backend use | localize Switch deployment mode\ndocket backup | restore Encrypted full-device backup\ndocket web Ensure the Web UI is running\ndocket check-update | update Version management\n```\n\n`docket help` prints the canonical, always-current list. Full flag-by-flag\nreference and the complete environment-variable table:\n**[`docs/cli.md`](docs/cli.md)**.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `todo_add(title, description?, list?, category?, priority?, dueDate?, sourceUrl?)` | Add an item. `list` is `\"todo\"` (default) or `\"backlog\"`. |\n| `todo_edit(id, ...)` | Edit any subset of fields by id. Pass `\"\"` to clear an optional field. |\n| `todo_claim(id)` | Mark an item as actively worked on. Advisory in Local Mode (warns/lets you take over); atomic in Self-hosted Mode. Auto-expires after 15 minutes. |\n| `todo_release(id)` | Clear your claim without completing the item. |\n| `todo_list(filter?, list?, category?, agent?, session?, inProgress?, limit?, offset?)` | List with filtering and token-saving pagination. |\n| `todo_complete(id)` | Mark done (also clears any claim). |\n| `todo_history(id)` | Full change log for one item. |\n| `todo_version()` | Data-format version and process start time. |\n| `todo_delete(id)` | Permanently remove an item. |\n| `todo_check_update()` | Check npm for a newer version (read-only). |\n\nIdentical behavior in both deployment modes. Full field/workflow reference:\n[`skills/docket-claim/SKILL.md`](skills/docket-claim/SKILL.md).\n\n## Web UI\n\nA real-time read/write dashboard — `http://localhost:8787` by default in\nLocal Mode (override with `DOCKET_WEB_PORT`), or the Docket Server's own URL\nin Self-hosted Mode. Light/dark theme, search, sort, inline edit,\nundo-delete, responsive mobile layout.\n\nIn Local Mode it starts itself: the first MCP client to connect spawns it\ndetached in the background if nothing's listening yet, and it keeps running\nafter that short-lived MCP connection exits — no separate install step, zero\noverhead until it's actually used. Updates push live over Server-Sent Events\n(`/api/events`) whenever an agent or peer changes a task, no polling.\n\nOpening it from another device on your LAN (phone, tablet) requires an\nexplicit **Viewer Gate** approval from the host machine first — see\n[Security](#security).\n\n## Devices & P2P sync\n\nPair a second computer and both keep the same list, entirely within **Local\nMode** — off by default, nothing connects until you open the Devices panel\nand start a pairing with an explicit Approve/Deny on the host device. This is\na *different topology* from Self-hosted Mode (see [Architecture](#architecture)):\nP2P sync replicates a full writable copy onto each paired device, merged\nfield-by-field on reconnect; a Docket Server instead owns the one\nauthoritative copy every client forwards to.\n\nFull pairing steps, the host/guest model, the X25519+HMAC+AES-GCM trust\nmodel, and how the merge algorithm actually works:\n**[`docs/p2p-sync.md`](docs/p2p-sync.md)**.\n\n## Security\n\nDocket has **four separate threat models** (encrypted local storage, P2P\nsync, the LAN Viewer Gate, and self-hosted client/server traffic) — a\nguarantee from one does not apply to another. The basics:\n\n- **At rest**: the data file is AES-256-GCM encrypted with a locally\n generated key — protects against accidental exposure, not against someone\n with read access to your own user account.\n- **P2P sync**: X25519 ECDH + HKDF-derived per-pair secrets, HMAC-signed\n requests with replay protection, AES-256-GCM encrypted responses. Nothing\n usable to a passive LAN listener.\n- **LAN Viewer Gate**: any browser other than the host machine needs explicit\n human approval before it can open the dashboard; that local traffic itself\n is plain HTTP, not TLS (documented tradeoff, not an oversight).\n- **Self-hosted mode**: every request is authenticated with a per-device\n HMAC signature (domain-separated from the P2P secret) with timestamp+nonce\n replay protection; a non-loopback `http://` server URL is refused unless\n explicitly opted into. The server itself is **not** end-to-end encrypted\n against its own operator — it holds the authoritative plaintext workspace\n while running.\n- **Updates**: every release is published with Sigstore-backed npm\n provenance, verifiable with `npm audit signatures`.\n\nNone of this is simplified into vague \"military-grade encryption\" claims —\nthe full threat model, exact primitives, replay-protection details, and\nself-hosted-specific limitations are in **[`docs/security.md`](docs/security.md)**.\n\n## Data & encryption\n\nAuthoritative data lives on this client machine (`~/.docket`) in Local Mode,\nor on the Docket Server in Self-hosted Mode — either way, on infrastructure\nyou control, never a hosted Docket account.\n\n- `todos.json.enc` — the store, AES-256-GCM encrypted\n- `key` — a locally generated 256-bit key, `chmod 600` (owner-read-only)\n- `device.json` — this machine's id, name, and X25519 identity keypair (private half never leaves this file)\n- `peers.json.enc` — paired P2P devices and their derived sync secrets\n\nSet `DOCKET_DATA_DIR` to relocate/share the directory explicitly; startup\nrefuses to silently split an existing store rather than guessing. If you\nupgrade from a version before encryption existed, the old plaintext\n`todos.json` is migrated automatically and kept as `todos.json.bak`.\n\n## Backup\n\n`docket backup ` bundles the whole data directory — identity, at-rest\nkey, todos, paired P2P peers — into one password-protected file (AES-256-GCM,\nkey derived with scrypt). `docket restore ` decrypts and writes it\nback, renaming what's currently on disk aside rather than overwriting it.\nStore the file and its password separately — losing either makes it useless,\nlosing both makes it unrecoverable. Refuses in Self-hosted Mode; back up on\nthe server itself instead.\n\n## Updating\n\n```sh\ndocket check-update # read-only — reports current vs. latest\ndocket update # checks, confirms, installs, self-tests, rolls back on failure\n```\n\nApplies to a **global npm install** only; `npx` always runs latest, and a\n`git clone` checkout updates with `git pull && npm run build`. Every release\nships with Sigstore npm provenance — see [Security](#security).\n\n## Testing\n\n```sh\nnpm test\n```\n\nRuns the full `node:test` suite — P2P sync merge, encryption round-trips,\npairing handshake verification, export/import, and (Self-hosted Mode) the\ndevice HMAC auth scheme plus `docket serve`'s full `/api/v1` lifecycle\nend-to-end.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
"bytes": 14379,
"sha": "7497234104063a4b43e60b4953e909bef81dbea7c96afda1490bfd9f70baafa9",
"repo_slug": "pasichdev/docket",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_pasichdev_docket_d6511f18/readme"
}
![\"Docket](\"docs/assets/demo-dark.jpg\")
\n ![\"Docket](\"docs/assets/demo-light.jpg\")
\n