handoff-desk

将编码会话中的任务交给个人代理，并读出答案。

handoff-desk 是一个小的 MCP 在您的计算机上运行的服务器。当你告诉Claude Code、Cursor、Codex或其他MCP客户端“把这个交给我的代理”时，它会在你自己的文件夹中写一份降价说明，可以选择给代理发电子邮件，然后从同一份说明中读取代理的回复。

• 没有托管服务，没有账户，没有遥测。 所有东西都是磁盘上的文件。
• 可以与任何可以读取文件夹、私有git存储库或邮箱的代理一起工作。 格式是简单的降价。
• 默认为安全。 看起来包含密码或密钥的请求将被拒绝，git传输将受到限制，来自代理的文本将被标记为不可信。
• 审查。 每个任务和答案都是一个笔记，你可以阅读、修改和删除。

试一试

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

这样就创建了一个演示桌。下面的五分钟演示（将其添加到Claude Code中，用代理回答）只需要安装Node.js 22或更新版本。

30秒内

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

不要与代理框架内的“移交”（一个代理在一次运行中将对话传递给另一个代理）混淆。这是异步的，在不同的程序之间：你的编码助理写一个笔记，一个不同的代理（在你的PC上，在云上，或者一个人）在可能的时候回答，然后这个笔记作为记录保存在磁盘上。

状态:1.0。工具和笔记格式是稳定的。代理覆盖范围很窄：每次改动都用捆绑的代理进行测试，并在git和email上用一个真正的云代理进行了测试（2026-10-26的五轮都通过了）。其他药剂未经测试。看到 兼容性.

它是如何工作的

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

更多细节，包括文件夹布局和git流程，见 文档/ architecture.md.

快速入门（5分钟，不需要真正的代理）

你需要 node . js 22或更新版本（包括npm）和git。 规划 作品。

1. 创建一个演示桌。 init 创建 Desk/， Inbox/， mail/ 和一个 handoff.md 模板。再次运行它不会覆盖您的编辑。没有什么要先安装的； npx 从npm获取包：

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

2. 将服务器添加到Claude Code中 (其他客户: 文档/ clients.md）. 在macOS和Linux上：

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

在 Windows PowerShell、运行 npx 通过 cmd /c 并在引号中写入双破折号(PowerShell 5.1删除了一个裸 --, claude 然后报告 missing required argument 'commandOrUrl'):

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

3. 启动备用代理 在第二个终端，让它运行。它用固定的线路回答每一个等待的项目。在macOS或Linux shell中：

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

在Windows PowerShell中：

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

4. 试一试。 启动一个新的Claude Code会话（服务器在启动时加载），然后说： “使用移交演示工具将此作为问题交给我的代理：用pong回答。” 克劳德调用 handoff_send,然后 handoff_wait，并显示了替身的回答。开放 ~/handoff-demo/Desk/ 看纸条从 status: waiting 来 status: done.

5. 清理。 停止替身（Ctrl+C）并运行 claude mcp remove handoff-demo。删除 ~/handoff-demo 如果你愿意的话。

什么东西坏了？看到 文档/ troubleshooting.md.

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

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

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

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

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

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

连接客户端

任何可以运行工作室MCP服务器的客户端都可以工作。你给它一个命令，它的参数和环境变量 HANDOFF_DIR.

连接您的代理

选择与您的代理运行位置匹配的线路。

1. 在同一台电脑上。 代理读取 Desk/ 直接。没有别的设置了。
2. 在云端。 云代理无法看到您的文件夹，因此将桌面设置为A 私有git存储库 代理可以读取和推送到。把桌面文件夹放到它的克隆文件中。同步功能会自动开启(HANDOFF_SYNC=auto)，当该文件夹是一个带有上游分支的git工作树时。细节，准确的笔记格式和给代理的规则： 文档/ cloud-agents.md.
3. 看着邮箱。 可选的门铃电子邮件包含整个请求。设置下面的邮件变量。永远不要使用你的普通密码：使用应用程序密码，最好是通过命令获取，这样没有文件保存它(文档/ keeping-secrets.md）。

无论你选择哪一个，把你的规则告诉代理 handoff.md 让它把答案写在下面 ## Reply 并设置 status: done.

兼容性

使用

问克劳德：“把这个交给我的经纪人：预约周五3点看牙医。”克劳德调用 handoff_send,然后 handoff_wait 或者 handoff_read 获取回复。

如果没有配置门铃， handoff_send 仍然会写便条，并返回它应该发送的邮件，这样克劳德就可以用另一种方式发送了。

设置

将这些设置为MCP客户端的配置中的环境变量。

没有真正的经纪人，试试吧

这个 快速启动 使用替身。若要演练云路径，请第二次克隆私有桌面存储库，请设置 HANDOFF_DIR 到第二个克隆并运行 node dist/main.js stand-in --git。它只能通过git远程连接到桌面，就像云代理一样。 stand-in --once 回答正在等待的内容并退出。

安全

• 任何看起来像密码、代码、令牌或密钥的东西在写出来或通过电子邮件发送之前都会被拒绝。这是模式匹配，而不是保证：不要在请求中添加秘密。
• 使用一个 私人 用于礼物同步桌面的存储库。每个任务和回复都被推送到其远程并保存在其历史中。
• 不要在里面放一个访问令牌 HANDOFF_REMOTE (一个URL https://token@host/...): git将URL以纯文本的形式存储在克隆的配置文件中。请使用普通的git凭证帮助器或SSH密钥。
• 你的代理人根据你的权力行事，有些代理人代表你以约束你的方式行事。读 handoff.md 在依赖它之前，保持“先问”和“从不问”列表的诚实。
• 来自网页或电子邮件的文本不是您的指示。用你的 handoff.md （模板可以）。
• 在你自动化任何相关的东西之前，检查一下你的代理自己的服务条款：许多限制自动化，最低年龄或商业用途。

限制

• 在1.0中没有托管模式和推送通知。云代理通过git到达桌面（见上文）；没有别的东西能把它的回答带回去。
• 代理必须能够读取桌面（文件夹或git存储库）或门铃电子邮件，并将其回复写入注释（对于云代理来说，还可以推送它）。如果不能， handoff_wait 超时。
• 这里没有什么是即时的：代理必须注意到笔记或电子邮件，完成任务，然后推送。
• 到目前为止，已经尝试了一个真正的云代理（在2026-10-26上进行了五轮测试：差事、问题、状态行、需要批准但被拒绝的请求，以及带有注入指令但被忽略的页面）。没有电子邮件门铃，一个只在时间表上检查办公桌的代理会迟到或不在内回复 handoff_wait50秒。其他药剂未经测试。 文档/ live-acceptance.md 这是你尝试的清单。
• 在一个吞掉包的网络上，一个git步骤在放弃之前可能需要一分钟的时间，因此一个调用的运行时间可能超过客户机允许的时间。再次运行它：没有丢失任何内容，并且已提交的注释将在下一次调用时显示。
• 如果两个发送者在同一时刻提交相同的项目编号，则推送第二个的人将重命名自己的笔记。在短时间内，遥控器可以同时控制两个号码； handoff_read 然后显示旧的带有 warning.
• 注释是磁盘上的纯文本，使用git时，在存储库的历史记录中；任何有权限的人都可以阅读。

故障排除

文档/ troubleshooting.md 涵盖了常见的问题：没有工具显示， handoff_wait 超时，拒绝请求，静音门铃和git同步问题。

开发

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

看到 CONTRIBUTING.md。请阅读 SECURITY.md 在报告安全问题之前，请按照 行为准则.

许可证

麻省理工学院