Skip to main content
Glama
README.md
<img src=".github/brand/banner.jpg" width="100%" alt="A canoe loaded with a tied bundle of notes, leaving a lantern-lit dock at night.">

<img src=".github/brand/icon.png" align="right" width="112" alt="handoff-desk icon">

# handoff-desk

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

[![npm](https://img.shields.io/npm/v/@voyageurworks/handoff-desk.svg)](https://www.npmjs.com/package/@voyageurworks/handoff-desk)
[![CI](https://github.com/voyageurworks/handoff-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/voyageurworks/handoff-desk/actions/workflows/ci.yml)
[![Security](https://github.com/voyageurworks/handoff-desk/actions/workflows/security.yml/badge.svg)](https://github.com/voyageurworks/handoff-desk/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522-339933.svg)](package.json)
[![Claude Code: verified with mcp-proof](proof/badges/claude-code.svg)](proof/table.md)

`handoff-desk` is a small [MCP](https://modelcontextprotocol.io) 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:

```sh
npx -y @voyageurworks/handoff-desk setup
```

Or paste [a ready-made prompt](docs/setup-prompt.md) into an AI assistant that can run commands and let it do the steps. For just a demo desk:

```sh
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

```text
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](#compatibility).

## How it works

```mermaid
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](docs/architecture.md).

## Quick start (5 minutes, no real agent needed)

You need [Node.js](https://nodejs.org) 22 or newer (this includes npm) and git. [pnpm](https://pnpm.io) 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:

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

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

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

```powershell
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:

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

In Windows PowerShell:

```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.

`init` prints these commands again with your real folder filled in, and `npx -y @voyageurworks/handoff-desk --help` lists every command. Something not working? Run `npx -y @voyageurworks/handoff-desk doctor`, then see [docs/troubleshooting.md](docs/troubleshooting.md).

<details>
<summary>Building from source instead (contributors)</summary>

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

```sh
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.

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

**3. Add the server to Claude Code** (other clients: [docs/clients.md](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`):

```sh
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'`:

```powershell
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:

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

In Windows PowerShell:

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

</details>

## Claude Code, Cursor and Codex

handoff-desk is built for these three. In each, the assistant uses the same 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`).

| | Claude Code | Cursor | Codex (CLI and IDE) |
| --- | --- | --- | --- |
| Set up | `claude mcp add` | `install --client cursor`, or `mcp.json` | `codex mcp add`, or `config.toml` |
| What has been run | The real client connected to the server (Windows 11) | The config is launched by a test and the install command is tested on a copy of Cursor's settings file; **the Cursor app itself has not been run** | The real client started the server, called `handoff_send`, a note was created, answered and read back (a scripted stand-in model, Windows 11) |
| Good to know | | | Codex asks before calling `handoff_send`; approve it, or pre-approve it in `config.toml` ([docs/clients.md](docs/clients.md#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`.

| Client | Guide |
| --- | --- |
| Claude Code | `claude mcp add` (above) |
| Cursor | `mcp.json`, see [docs/clients.md](docs/clients.md#cursor) |
| VS Code (Copilot agent mode) | `.vscode/mcp.json`, see [docs/clients.md](docs/clients.md#vs-code-github-copilot) |
| Codex (CLI and IDE) | `codex mcp add` or `config.toml`, see [docs/clients.md](docs/clients.md#codex) |
| Claude Desktop | `claude_desktop_config.json`, see [docs/clients.md](docs/clients.md#claude-desktop) |
| Gemini CLI, OpenCode, Kilo Code, Amp, Continue, Goose, Junie CLI, Windsurf, LM Studio, Cline, Roo Code, Amazon Q | `handoff-desk config --client <name>` or `install`, see [docs/clients.md](docs/clients.md#every-other-client) |

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 and Amp work the same way). `npx -y @voyageurworks/handoff-desk doctor` checks your setup and says what to fix.

**Not supported yet:** Kiro, Warp, the JetBrains IDEs (the Junie CLI above was run) and Zed. `config --client` still prints a block for each from the client's own documentation, but none has been run, so expect to adjust it ([docs/clients.md](docs/clients.md#not-supported-yet)).

## 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](docs/cloud-agents.md).
3. **OpenClaw.** OpenClaw can be the agent: it reads and answers notes with `handoff_pending` and `handoff_answer`, and an optional wake call tells it a note is waiting. Setup, and what the wake call does and never sends: [docs/openclaw.md](docs/openclaw.md).
4. **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](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](docs/agent-contract.md).

### Compatibility

| Agent | Status |
| --- | --- |
| Bundled stand-in (`stand-in` command) | Tested on every change |
| Claude Code 2.1.322 | `verified` by [mcp-proof](https://github.com/voyageurworks/mcp-proof) 0.1.4 on 2026-11-11: the published 1.2.4, started by the real client in a throwaway home on Windows 11, answered the handshake and `tools/list` (record and badge in [proof/](proof/table.md)). Not a test of the tools themselves, and not run on macOS or Linux |
| Operating systems and shells | Tests run on Linux and Windows on every change. macOS (Intel and Apple silicon) runs in a separate workflow on every pull request, but GitHub's macOS runners are sometimes unavailable, and then the check says macOS was not verified. The quick start runs under bash and zsh on Linux and macOS, and in Windows PowerShell 5.1 by hand |
| Cursor, VS Code (Copilot), Claude Desktop, Codex | The config examples in [docs/clients.md](docs/clients.md) are launched by a test and complete an MCP handshake. The editors themselves are not run in CI |
| Codex, Gemini CLI, Goose, Junie CLI, OpenCode, Kilo Code (CLI), Continue (CLI) | Started the server from the config `handoff-desk config` prints and showed it connected or completed the handshake, on Windows 11 (versions in [docs/clients.md](docs/clients.md#every-other-client)). Not re-run in CI, and not run on macOS or Linux |
| Telegram and Slack doorbells | The built program was run against a local stand-in for both services: the exact requests, 429, 500, a dropped connection and nothing listening. Not yet against live accounts |
| One real cloud agent, over git and email | Five rounds passed on 2026-10-26. A re-run the next day without the email doorbell was only partly answered, because that agent checks the desk on a schedule; with the doorbell on it is expected to react sooner but that has not been re-tested |
| Any other agent that can read markdown files in a folder or repository | Expected to work, not tested. [docs/live-acceptance.md](docs/live-acceptance.md) is the checklist for trying yours |

## 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.

| Tool | What it does |
| --- | --- |
| `handoff_send` | Errand, question or status for the agent (note plus optional doorbell email) |
| `handoff_status` | One-line status update |
| `handoff_list`, `handoff_read` | See items and read one in full |
| `handoff_wait` | Wait up to 50 seconds for the agent's answer (call again to keep waiting) |
| `handoff_capabilities` | What your `handoff.md` says the agent may do alone, must ask first, or never do |
| `handoff_inbox`, `handoff_inbox_reply` | Read and answer notes the agent left for Claude |
| `handoff_pending`, `handoff_answer` | For the agent side only (for example OpenClaw): the waiting items with their requests, and a checked way to answer one. A sender such as Claude Code never calls them |

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.

| Variable | Default | Meaning |
| --- | --- | --- |
| `HANDOFF_DIR` | `~/handoff` | Desk folder |
| `HANDOFF_MAIL_USER` | none | Sender address for the doorbell |
| `HANDOFF_MAIL_APP_PASSWORD` | none | App password for that sender (never your normal password) |
| `HANDOFF_MAIL_PASSWORD_COMMAND` | none | A command that prints the app password, run only when a doorbell is sent, so no file holds it (password manager, encrypted store; see docs). Used when `HANDOFF_MAIL_APP_PASSWORD` is not set |
| `HANDOFF_ENV_FILE` | none | Path to a private file of `NAME=value` lines (any setting in this table). Keeps the app password out of your MCP client's config. Real environment values win over the file. Keep the file outside the desk repository and readable only by you |
| `HANDOFF_MAIL_TO` | none | The agent's mailbox |
| `HANDOFF_SMTP_HOST`, `HANDOFF_SMTP_PORT` | `smtp.gmail.com`, `465` | Mail server |
| `HANDOFF_MAIL_DIR` | `<HANDOFF_DIR>/mail` | Where email copies go |
| `HANDOFF_TZ` | system zone | Time zone for timestamps |
| `HANDOFF_SYNC` | `auto` | `auto`: sync through git when `HANDOFF_DIR` is a work tree with an upstream. `git`: require it (an error otherwise). `off`: local folder only |
| `HANDOFF_REMOTE` | none | Clone this repository into `HANDOFF_DIR` the first time a desk tool is used |
| `HANDOFF_GIT_NAME`, `HANDOFF_GIT_EMAIL` | the repository's git config, else `handoff-desk` | Identity for the desk's commits |
| `HANDOFF_INBOX_DIR` | `Inbox` | Folder where the agent leaves notes for Claude |
| `HANDOFF_SUBJECT_PREFIX` | `Handoff` | Subject of the doorbell email: `[<prefix> errand #3] ...` |
| `HANDOFF_TELEGRAM_BOT_TOKEN`, `HANDOFF_TELEGRAM_BOT_TOKEN_COMMAND` | none | Optional Telegram doorbell: the bot's token, or a command that prints it (see [Chat doorbells](#chat-doorbells-telegram-and-slack)) |
| `HANDOFF_TELEGRAM_CHAT_ID` | none | The chat the bot writes to (a number; a group's starts with `-`; or a public `@channel`) |
| `HANDOFF_SLACK_WEBHOOK_URL`, `HANDOFF_SLACK_WEBHOOK_COMMAND` | none | Optional Slack doorbell: an incoming-webhook URL (`https://hooks.slack.com/services/...`), or a command that prints it |
| `HANDOFF_OPENCLAW_WAKE_URL`, `HANDOFF_OPENCLAW_HOOK_TOKEN`, `HANDOFF_OPENCLAW_HOOK_TOKEN_COMMAND`, `HANDOFF_OPENCLAW_AGENT_ID` | none | Optional wake call to an OpenClaw Gateway after each send: its `/hooks/wake` address (`https://`, or `http://` to this computer), the hook token (or a command that prints it) and, with several agents, the agent id. Carries only the item number and type, never the title or request ([docs/openclaw.md](docs/openclaw.md)) |
| `HANDOFF_STATE_DIR` | `~/.handoff-desk/state` | Where the list of chat doorbells to re-send is kept (on this computer only, never in the desk or git) |
| `HANDOFF_NOTIFY_INCLUDE_REQUEST` | off | `1` adds the first 500 characters of the request to the Telegram and Slack messages. By default they carry only the id, type, title and note name |

## 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.
- **Step-by-step setup for both, including how to find the chat id and make the Slack webhook: [docs/chat-doorbells.md](docs/chat-doorbells.md).**
- **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](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). **Also tested live (2026-11-03, version 1.2.1, a test bot and a test Slack workspace, private chat and channel):** a real `handoff_send` rang Telegram and Slack on Windows 11 and on Linux (Ubuntu 26.04, Node 24), and `doctor --ping` sent to both; Telegram also rang on macOS 15 (Intel, a GitHub runner). A wrong token (Telegram 401), a dead webhook (Slack 404) and a webhook on another host were reported as not sent, as designed. **Not tested live:** Slack on macOS, Apple-silicon macOS, group chats and channels, 429 and the retry list against the real services. Try it 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.

```sh
npx -y @voyageurworks/handoff-desk config --client cursor --dir ~/handoff > mcp.json
```

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](mcp.json) in the same format.

## Try it without a real agent

The [quick start](#quick-start-5-minutes-no-real-agent-needed) 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](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](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

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

See [CONTRIBUTING.md](CONTRIBUTING.md). Please read [SECURITY.md](SECURITY.md) before reporting a security problem, and follow the [code of conduct](CODE_OF_CONDUCT.md).

## More from Voyageur Works

Separate tools from the same studio; each works without the others.

- [launch-guard-pack](https://github.com/voyageurworks/launch-guard-pack): check a private git repository, or the npm package you are about to publish, before it goes public, without printing what it finds.
- [mcp-proof](https://github.com/voyageurworks/mcp-proof): prove an MCP server really starts in real clients, with dated, labelled evidence you can paste into a README.

## License

[MIT](LICENSE)

TDQS

A3.6/5.0

Scored across 10 tools

Disambiguation3/5

Several pairs have blurry boundaries: handoff_pending vs handoff_list (both enumerate desk items, one filtered by 'waiting'), handoff_send vs handoff_status (status is essentially a lightweight send), and handoff_answer vs handoff_inbox_reply (two reply tools that differ only by direction). The descriptions do explicitly note which role calls what ('a sender never calls this'), which rescues the set, but the dual-role sender/answerer split plus inbox-vs-pending directionality requires careful reading before an agent picks correctly.

Naming Consistency4/5

All ten tools share the handoff_ prefix and consistent snake_case, so the family is immediately recognizable. The only wobble is grammatical form: mostly verbs (send, answer, list, read, wait) mixed with nouns/adjectives (status, pending, capabilities, inbox) and one reversed compound (handoff_inbox_reply).

Tool Count4/5

Ten tools is well within a comfortable range for a two-party handoff protocol, and each maps to a real step (send, list, read, wait, answer, status, capabilities, inbox lifecycle). A couple are thin — handoff_status is nearly a special case of handoff_send, and handoff_pending largely duplicates a filtered handoff_list — but nothing is gratuitous.

Completeness4/5

The core lifecycle is covered end to end: compose, list, read, poll for reply, answer, plus the auxiliary inbox and capability-rules surfaces. The notable gap is no cancel/withdraw/delete for a sent note and no search across items, so a request sent in error or an obsolete item has no cleanup path.

Maintenance

ActivityNo data
ResponsivenessOutdated data