handoff-desk

handoff-desk

Hand tasks from your coding session to a personal agent, and read the answer back.

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

npx -y @voyageurworks/handoff-desk init ~/handoff-demo

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

You, in Claude Code:  "Hand this to my agent: book the dentist for Friday at 3."
handoff-desk writes:  Desk/2026-11-02 Item 01 - Book dentist.md   (status: waiting)
Your agent (any):     reads the note, does the task, writes "## Reply", sets status: done
You, same chat:       "What did my agent say?"  ->  the reply, read back from that note

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

sequenceDiagram
    participant You as You + MCP client
    participant HD as handoff-desk (on your computer)
    participant Desk as Desk folder / private git repo
    participant Agent as Your agent
    You->>HD: handoff_send("book the dentist")
    HD->>Desk: write Desk/2026-10-29 Item 01 - dentist.md (status: waiting)
    HD-->>Agent: optional doorbell email
    Agent->>Desk: read note, do the task, write "## Reply", status: done
    You->>HD: handoff_wait / handoff_read
    HD->>Desk: read (and pull, with git)
    HD-->>You: the agent's reply

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:

npx -y @voyageurworks/handoff-desk init ~/handoff-demo

2. Add the server to Claude Code (other clients: docs/clients.md). On macOS and Linux:

claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" -- npx -y @voyageurworks/handoff-desk

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'):

claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" '--' cmd /c npx -y '@voyageurworks/handoff-desk'

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:

HANDOFF_DIR="$HOME/handoff-demo" npx -y @voyageurworks/handoff-desk stand-in

In Windows PowerShell:

$env:HANDOFF_DIR = "$HOME/handoff-demo"
npx -y @voyageurworks/handoff-desk stand-in

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):

git clone https://github.com/voyageurworks/handoff-desk.git
cd handoff-desk
npm install
npm run build

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.

node dist/main.js init ~/handoff-demo

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):

claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" -- node /absolute/path/to/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':

claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" '--' node C:/absolute/path/to/handoff-desk/dist/main.js

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:

cd handoff-desk
HANDOFF_DIR="$HOME/handoff-demo" node dist/main.js stand-in

In Windows PowerShell:

cd handoff-desk
$env:HANDOFF_DIR = "$HOME/handoff-demo"
node dist/main.js stand-in

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.

Connect your agent

Pick the line that matches where your agent runs.

1. On the same computer. The agent reads Desk/ directly. Nothing else to set up.
2. 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.
3. 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.

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.

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

pnpm install
pnpm check   # type-check
pnpm test    # full suite, including an end-to-end test over real stdio

See CONTRIBUTING.md. Please read SECURITY.md before reporting a security problem, and follow the code of conduct.

License

MIT