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

New here? One command asks who sends the notes and who answers them (an agent on this computer, OpenClaw or a cloud agent), creates the desk and prints every step with your folder filled in:

npx -y @voyageurworks/handoff-desk setup

Or paste a ready-made prompt into an AI assistant that can run commands and let it do the steps. For just a demo desk:

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

... View full README on GitHub