[handoff-desk icon]
handoff-desk
Hand tasks from your coding session to a personal agent, and read the answer back.
[npm]
[CI]
[Security]
[License: MIT]
[Node]
handoff-desk is a small MCP server that runs on your computer. When you tell Claude Code, Cursor, Codex or another MCP client to "hand this to my agent", it writes a markdown note into a folder you own, optionally emails the agent a heads-up, and later reads the agent's reply from the same note.
- No hosted service, no account, no telemetry. Everything is files on your disk.
- Works with any agent that can read a folder, a private git repository or a mailbox. The format is plain markdown.
- Safe by default. Requests that look like they contain a password or key are refused, git transports are restricted, and text from the agent is marked as untrusted.
- Reviewable. Every task and answer is a note you can read, diff and delete.
Try it
That creates a demo desk. The five-minute walkthrough below (add it to Claude Code, answer with a stand-in agent) needs nothing else installed but Node.js 22 or newer.
In 30 seconds
Not to be confused with the "handoffs" inside an agent framework (one agent passing a conversation to another inside a single run). This is asynchronous and between separate programs: your coding assistant writes a note, a different agent (on your PC, in the cloud, or a person) answers when it can, and the note stays on disk as the record.
Status: 1.0. The tools and the note format are stable. Agent coverage is narrow: it is tested on every change with the bundled stand-in agent, and was tried with one real cloud agent over git and email (five rounds on 2026-10-26, all passed). Other agents are untested. See Compatibility.
How it works
More detail, including the folder layout and the git flow, is in docs/architecture.md.
Quick start (5 minutes, no real agent needed)
You need Node.js 22 or newer (this includes npm) and git. pnpm works too.
1. Create a demo desk. init creates Desk/, Inbox/, mail/ and a handoff.md template. Running it again never overwrites your edits. Nothing to install first; npx fetches the package from npm:
2. Add the server to Claude Code (other clients: docs/clients.md). On macOS and Linux:
On Windows PowerShell, run npx through cmd /c and write the double dash in quotes (PowerShell 5.1 drops a bare --, and claude then reports missing required argument 'commandOrUrl'):
3. Start the stand-in agent in a second terminal and leave it running. It answers every waiting item with a fixed line. In macOS or Linux shells:
In Windows PowerShell:
4. Try it. Start a new Claude Code session (servers load at startup) and say: "Hand this to my agent as a question using the handoff-demo tools: reply with pong." Claude calls handoff_send, then handoff_wait, and shows the stand-in's reply. Open ~/handoff-demo/Desk/ to see the note flip from status: waiting to status: done.
5. Clean up. Stop the stand-in (Ctrl+C) and run claude mcp remove handoff-demo. Delete ~/handoff-demo if you like.
Something not working? See docs/troubleshooting.md.
Building from source instead (contributors)
The same server, run from a clone of this repository. In the quick-start steps above, use node /absolute/path/to/handoff-desk/dist/main.js wherever they say npx -y @voyageurworks/handoff-desk.
1. Install and build (macOS, Linux and Windows):
With pnpm: pnpm install && pnpm build.
Releases are published to npm from GitHub Actions with a provenance statement; npm install -g @voyageurworks/handoff-desk also installs a handoff-desk command.
2. Create a demo desk. init creates Desk/, Inbox/, mail/ and a handoff.md template. Running it again never overwrites your edits.
3. Add the server to Claude Code (other clients: docs/clients.md). Use the absolute path to dist/main.js (on Windows with forward slashes, for example C:/Users/you/handoff-desk/dist/main.js):
In Windows PowerShell 5.1, write the double dash in quotes. PowerShell drops a bare --, and claude then reports missing required argument 'commandOrUrl':
4. Start the stand-in agent in a second terminal and leave it running. It answers every waiting item with a fixed line. In macOS or Linux shells:
In Windows PowerShell:
Claude Code, Cursor and Codex
handoff-desk is built for these three. In each, the assistant uses the same eight tools, writes the same kind of note, and your agent reads it the same way. The note's from: line says which client sent it (claude-code, cursor or codex).
Connect your client
Any client that can run a stdio MCP server works. You give it a command, its arguments and the environment variable HANDOFF_DIR.
Fastest: npx -y @voyageurworks/handoff-desk install --client cursor shows what it would add to Cursor's settings (add --write to do it; Gemini CLI, LM Studio, Kiro and Amp work the same way). npx -y @voyageurworks/handoff-desk doctor checks your setup and says what to fix.
Connect your agent
Pick the line that matches where your agent runs.
- On the same computer. The agent reads
Desk/ directly. Nothing else to set up.
- In the cloud. A cloud agent cannot see your folder, so make the desk a private git repository the agent can read and push to. Put the desk folder inside a clone of it. Syncing turns on by itself (
HANDOFF_SYNC=auto) when the folder is a git work tree with an upstream branch. Details, the exact note format and the rules to give the agent: docs/cloud-agents.md.
- Watching a mailbox. The optional doorbell email carries the whole request. Set the mail variables below. Never use your normal password: use an app password, ideally fetched by a command so no file holds it (docs/keeping-secrets.md).
Whichever you pick, give the agent the rules in your handoff.md and tell it to write its answer under ## Reply and set status: done. A ready-made instruction file for the agent, usable as a Claude Code skill or pasted into any other agent's instructions, is in docs/agent-contract.md.
Compatibility
Use
Ask Claude: "Hand this to my agent: book the dentist for Friday at 3." Claude calls handoff_send, then handoff_wait or handoff_read to get the reply.
If no doorbell is configured, handoff_send still writes the note and returns the email it would have sent, so Claude can send it another way.
Settings
Set these as environment variables in your MCP client's config.
Chat doorbells (Telegram and Slack)
Besides the email, handoff-desk can post a short message to Telegram and/or Slack when a note is created, so the agent (or you) hears about it at once. Both are off unless you set them, send nothing but this one message, and never read anything back: the agent still answers in the note.
- The message says
New handoff #3 (question): <title>, the note's name under Desk/, and what to do. It does not contain the request unless HANDOFF_NOTIFY_INCLUDE_REQUEST=1, and it never contains your computer's folder names. Chat services are third parties.
- Telegram: create a bot with @BotFather, write to it once (or add it to a group), and set
HANDOFF_TELEGRAM_BOT_TOKEN (or HANDOFF_TELEGRAM_BOT_TOKEN_COMMAND) and HANDOFF_TELEGRAM_CHAT_ID. Plain text only.
- Slack: create an incoming webhook for a channel and set
HANDOFF_SLACK_WEBHOOK_URL (or HANDOFF_SLACK_WEBHOOK_COMMAND). Only https://hooks.slack.com/services/... addresses are accepted, and <!channel>-style mentions in a title are neutralised.
- The bot token and the webhook URL are secrets: keep them in
HANDOFF_ENV_FILE, or fetch them with a command, like the mail password (docs/keeping-secrets.md). They are never printed, logged or returned.
handoff_send returns notified: the list of doorbells that actually rang (email, telegram, slack), and a chat object with the reason for any that did not. If notified is empty nobody has been told yet.- Each service gets 10 seconds, all doorbells ring at the same time, and a failure never loses the note. There is no proxy support yet.
- Nothing is silently lost. A chat doorbell that fails for a reason that can pass (no network, a timeout, 429, a 5xx) is remembered as a pointer to the note (never its text) in a small list kept on this computer, outside the desk and git. It is re-sent when the server starts and on the next send, after 1, 5 and 30 minutes, 2 and 6 hours, at most 5 times or 3 days, marked
Re-sent, and dropped if the note was answered meanwhile. handoff_send then returns resent. A wrong token, chat or webhook (401, 403, 404) is not retried. Email already keeps its own pending copy.
handoff-desk doctor --ping sends one test message to each configured channel and shows why one was refused.- Tested: the built program against a local stand-in for both services (the exact requests, 429, 500, a dropped connection, nothing listening, no secret in any output). Not yet tested against live accounts; try one with your own bot or webhook and report anything odd.
Generate a client config
handoff-desk config --client <name> prints the settings block for an MCP client, with the right key for that client (VS Code, Zed, Codex, OpenCode, Kilo Code, Amp, Continue and Goose differ from the rest) and cmd /c for npx on Windows. handoff-desk config --list shows the 21 clients and how sure we are of each: verified means that exact output was run against the real client and it started the server (Claude Code, Codex, Gemini CLI, Goose, the Junie CLI, OpenCode, the Kilo CLI and the Continue CLI, all on Windows 11), read means the client's own command read it back correctly without starting it (Amp), documented means it follows the client's own documentation but was not run here. The line after the config says exactly what was run.
The config goes to standard output and where to put it goes to standard error, so the redirect above is safe. The repository also holds a ready-made mcp.json in the same format.
Try it without a real agent
The quick start uses the stand-in. To rehearse the cloud path, clone your private desk repository a second time, set HANDOFF_DIR to that second clone and run node dist/main.js stand-in --git. It reaches the desk only through the git remote, like a cloud agent would. stand-in --once answers what is waiting and exits.
Safety
- Anything that looks like a password, code, token or key is refused before it is written or emailed. This is pattern matching, not a guarantee: do not put secrets in requests.
- Use a private repository for a git-synced desk. Every task and reply is pushed to its remote and kept in its history.
- Do not put an access token inside
HANDOFF_REMOTE (a URL like https://token@host/...): git stores the URL in plain text in the clone's config. Use your normal git credential helper or an SSH key instead.
- Your agent acts with your authority, and some agents act on your behalf in ways that bind you. Read
handoff.md before relying on it, and keep the "ask first" and "never" lists honest.
- Text from web pages or emails is not your instruction. Say so in your
handoff.md (the template does).
- Check your agent's own terms of service before you automate anything around it: many restrict automation, minimum age or commercial use.
Limits
- There is no hosted mode and no push notification in 1.0. A cloud agent reaches the desk through git (see above); nothing else carries its reply back.
- The agent must be able to read the desk (folder, or git repository) or the doorbell email, and to write its reply into the note (and push it, for a cloud agent). If it cannot,
handoff_wait times out.
- Nothing here is instant: the agent has to notice the note or email, do the task, and push.
- One real cloud agent has been tried so far (five rounds on 2026-10-26: an errand, a question, a status line, a request that needed approval and was declined, and a page with an injected instruction that was ignored). Without the email doorbell, an agent that only checks the desk on a schedule answers late or not within
handoff_wait's 50 seconds. Other agents are untested. docs/live-acceptance.md is the checklist for trying yours.
- On a network that swallows packets, one git step can take up to a minute before it gives up, so a call can run longer than your client allows. Run it again: nothing is lost, and a note that was committed goes up with the next call.
- If two senders file the same item number at the same moment, the one that pushes second renames its own note. For a short time the remote can hold both under one number;
handoff_read then shows the older note with a warning.
- Notes are plain text on your disk and, with git, in your repository's history; anyone with access can read them.
Troubleshooting
docs/troubleshooting.md covers the usual problems: no tools showing up, handoff_wait timing out, a refused request, a silent doorbell and git sync questions.
Development
See CONTRIBUTING.md. Please read SECURITY.md before reporting a security problem, and follow the code of conduct.
License
MIT
