handoff-mcp-server
v0.49.0
Published
MCP server that gives AI coding agents persistent memory across sessions
Maintainers
Readme
handoff-mcp
An MCP server that gives AI coding agents persistent memory across sessions.
When you close a Claude Code session and start a new one, the new session has no idea what the previous one was doing. handoff-mcp solves this by saving session context — tasks, decisions, blockers, and file pointers — to a local .handoff/ directory that the next session can load automatically.
The Problem
AI coding sessions are stateless. Every new session starts from zero:
- "What was I working on?" — the agent doesn't know
- "What decisions were made?" — lost with the previous context window
- "What's left to do?" — you have to re-explain everything
This gets painful fast on multi-session projects.
How It Works
Session 1 Session 2
┌──────────────┐ ┌──────────────┐
│ Working... │ .handoff/ │ load_context │
│ │──────────────────>│ ↓ guidance │
│ save_context │ tasks/ │ save_context │
│ - close │ sessions/ │ (active) │
│ - summary │ config.toml │ ↓ work... │
│ - decisions │ │ save_context │
│ - blockers │ │ (close) │
└──────────────┘ └──────────────┘At session start, the agent calls handoff_load_context to pick up where things left off. If no active session exists, the response includes session_guidance prompting the agent to establish one via handoff_save_context with session_status: "active" — this creates a persistent .active.json that survives interruptions. At session end, the agent calls handoff_save_context (defaulting to session_status: "closed") to close the session.
Installation
Codex CLI plugin (recommended for Codex users)
Install the Handoff binary, add the GitHub marketplace, install the Codex Task Loop plugin, and register the Handoff MCP server:
npm install -g handoff-mcp-server
codex plugin marketplace add alphaelements/handoff-mcp
codex plugin add handoff-task-loop-codex@handoff-mcp-marketplace
codex mcp add handoff -- handoff-mcpConfirm the plugin and MCP server, then begin a new Codex session:
handoff-mcp --version
codex plugin list
codex mcp get handoffUse $handoff-session-loop only when you want to explicitly run ready Handoff
tasks through the Codex developer, tester, and reviewer loop. For regular
session continuity, use the Handoff MCP tools and this repository's
AGENTS.md guidance.
Local checkout: replace alphaelements/handoff-mcp with the absolute path
to this repository in the marketplace command. Reinstall the plugin after an
update and start a new Codex session so it reloads the bundled skill.
Direct MCP alternative: users who do not need the task loop can install the
binary and run only codex mcp add handoff -- handoff-mcp. This supplies the
Handoff tools but not $handoff-session-loop.
For a controlled non-interactive loop, permit Handoff MCP writes for that one
invocation; otherwise codex exec can cancel task-state changes:
codex exec -c 'mcp_servers.handoff.default_tools_approval_mode = "auto"' \
--sandbox workspace-write '$handoff-session-loop <scoped task request>'Updating: run codex plugin marketplace upgrade handoff-mcp-marketplace,
then reinstall with codex plugin add handoff-task-loop-codex@handoff-mcp-marketplace.
Update the binary separately with npm install -g handoff-mcp-server@latest
or cargo install handoff-mcp --force.
Claude Code compatibility: Codex uses
$handoff-session-loop; Claude Code uses/session-loopand/research-loop. The Codex plugin does not execute Claude commands, agents, or Workflow DSL.
Claude Code Plugin (recommended)
The easiest way to install handoff-mcp is as a Claude Code plugin.
# 1. Install the binary (required — the plugin calls it)
npm install -g handoff-mcp-server
# or: cargo install handoff-mcp
# 2. Add the marketplace (GitHub repo)
/plugin marketplace add alphaelements/handoff-mcp
# 3. Install the plugin (MCP server + skills)
/plugin install handoff-mcp@handoff-mcp-marketplace
# 4. Apply the change
/reload-pluginsThis registers the MCP server and all skills automatically — no manual
.mcp.json or skill file setup needed. The handoff-mcp plugin is enabled
on install, so no separate /plugin enable is needed. Run /reload-plugins
to pick up the change mid-session (a Claude Code restart also applies it).
Naming:
handoff-mcpis the plugin name;handoff-mcp-marketplaceis the marketplace name (thenamefield in.claude-plugin/marketplace.json). Install commands always use<plugin>@<marketplace>.
Platform support
The npm package ships prebuilt binaries — no Rust toolchain, no compiler, and no install scripts are needed. npm downloads only the binary matching your platform.
| Platform | x64 | arm64 | |---|---|---| | Linux (glibc 2.35+) | ✅ | ✅ | | macOS | ✅ | ✅ | | Windows | ✅ | ✅ |
WSL works as a plain Linux install. For anything else — musl/Alpine, FreeBSD,
32-bit, or glibc older than 2.35 — install with cargo install handoff-mcp
instead, which builds from source.
If you already have a binary you built yourself, point the npm wrapper at it
with HANDOFF_MCP_BINARY_PATH=/path/to/handoff-mcp.
Note: installing with
--omit=optionalskips the prebuilt binary and leaves the CLI unable to start. Reinstall without that flag.Alpine / musl: the Linux binaries are glibc-linked. npm may install one anyway, and it fails to exec with a confusing "not found" error even though the file is present. Use
cargo install handoff-mcpon musl systems.
Optional: task loop (automated TDD + research workflows)
/plugin install handoff-task-loop@handoff-mcp-marketplace
/plugin enable handoff-task-loop@handoff-mcp-marketplace
/reload-pluginsAdds /session-loop (parallel TDD implementation, adversarial testing, Opus
review), /research-loop (multi-agent investigation, verification, spec
drafting) and /bugfix-loop (one bug: failing test first, approval, fix, the
same test, the full suite). See plugin-task-loop/README.md.
Optional: memory auto-injection hooks
/plugin install handoff-mcp-hooks@handoff-mcp-marketplace
/plugin enable handoff-mcp-hooks@handoff-mcp-marketplace
/reload-pluginsThis adds hooks that inject relevant project memories on every prompt and file
edit. Disable anytime with /plugin disable handoff-mcp-hooks@handoff-mcp-marketplace —
the MCP server and skills remain active.
Important: The hooks require a
handoffMCP server entry in the project's.mcp.json. Runhandoff-mcp setup --mcp-jsonin the project directory to add it automatically, or add it manually:{ "mcpServers": { "handoff": { "type": "stdio", "command": "handoff-mcp", "args": [], "env": {} } } }Without this entry, the hooks will show "not connected" errors on every prompt. The plugin's built-in MCP server is accessible to tools but not to hooks — this is a Claude Code limitation.
The
handoff-task-loopandhandoff-mcp-hooksplugins ship withdefaultEnabled: false, so they need an explicit/plugin enablestep after install. The mainhandoff-mcpplugin isdefaultEnabled: trueand skips it.
Installing the local development version instead
If you are hacking on handoff-mcp and want Claude Code to load your local
checkout rather than the published GitHub version, register the repository root
(the directory containing .claude-plugin/marketplace.json) as a local
marketplace:
# 1. Build the binary and sync skills + plugin caches
./scripts/install-local.sh
# 2. Register the repo root as a local marketplace (first time only).
# Use the local path here — not the alphaelements/handoff-mcp shorthand.
/plugin marketplace add /absolute/path/to/handoff-mcp
# 3. Install and apply
/plugin install handoff-mcp@handoff-mcp-marketplace
/reload-pluginsAfter the first setup, re-run ./scripts/install-local.sh whenever you change
the code, then restart Claude Code (or /reload-plugins) to load the rebuilt
version. Note that install-local.sh only rebuilds the binary and refreshes
the plugin cache — it does not register the marketplace or enable the plugin,
so steps 2 and 3 are a one-time bootstrap.
Updating
If you installed handoff-mcp as a plugin, it updates along two independent
paths, and you need both. The plugin does not bundle the binary:
plugin.json registers the MCP server as command: "handoff-mcp", which
Claude Code resolves on your PATH. So the marketplace ships the skills and
the plugin manifest, while npm or cargo ships the executable that actually
implements the MCP tools.
(Installed without the plugin, via cargo install or npm install -g alone?
Then only step 1 and the restart apply.)
Updating only the plugin leaves you on the old MCP tools. Updating only the binary leaves you on the old skills.
# 1. Binary — this is what implements the MCP tools
npm install -g handoff-mcp-server@latest
# or: cargo install handoff-mcp --force
# 2. Marketplace catalog — fetch the new version list
/plugin marketplace update handoff-mcp-marketplace
# 3. Plugin — skills and manifest
/plugin update handoff-mcp@handoff-mcp-marketplace
# 4. Restart Claude CodeUpdate the optional plugins the same way if you installed them:
/plugin update handoff-task-loop@handoff-mcp-marketplace
/plugin update handoff-mcp-hooks@handoff-mcp-marketplaceSteps 1 and 3 update different things, and neither substitutes for the other.
/plugin update never touches the binary — it swaps the cached plugin directory,
which contains no executable at all — so no amount of restarting will give you
new MCP tools if you skipped step 1. Conversely, step 1 rewrites the file on disk
but the MCP server Claude Code already spawned keeps running the old image, so
you get the new tools only after step 4.
Step 4 is therefore not optional, and /reload-plugins is not a substitute: it
refreshes skills, not the MCP server process.
Do not expect step 1 to take effect on its own. An installer that overwrites a
running binary in place fails on Linux with Text file busy; installers that
replace the file instead (unlink, then create — what install-local.sh does)
succeed, and leave the already-running server executing the now-deleted old
image until it restarts. Either way, the new tools appear only after step 4.
Verify the update landed:
which handoff-mcp # the binary Claude Code will actually run
handoff-mcp --version
claude plugin list # plugin version, per marketplaceclaude plugin list reports the version you actually have installed. Note that
claude plugin details reads the marketplace source instead, so it shows the
version on offer whether or not you have updated to it — don't use it to
confirm an update.
Local development checkout: ./scripts/install-local.sh does both halves at
once (rebuilds the binary into ~/.local/bin and refreshes the plugin cache).
Restart Claude Code afterwards.
Troubleshooting
Plugin or skills don't show up — run
/reload-plugins, or restart Claude Code. As a last resort,rm -rf ~/.claude/plugins/cacheand reinstall.plugin not found— refresh the catalog with/plugin marketplace update handoff-mcp-marketplace, then reinstall.MCP server won't start — open
/plugin→ Errors tab, and confirm the binary is on yourPATH(which handoff-mcp).You updated, but the MCP tools still behave like the old version — you almost certainly updated the plugin without updating the binary, or you updated the binary but did not restart Claude Code. Work through the four steps above in order.
An older
handoff-mcpearlier on yourPATHshadows the new one. This is the most common cause of "I updated and nothing changed", becausenpm install -gandcargo installwrite to different directories. List every copy and see which one wins:type -a handoff-mcp # every match, in resolution order for d in ${PATH//:/ }; do [ -x "$d/handoff-mcp" ] && echo "$d -> $("$d/handoff-mcp" --version)" doneThe first line is the one Claude Code runs. Remove the stale copies (e.g.
cargo uninstall handoff-mcp, or delete the old file), or put the directory holding the current binary earlier on yourPATH.--versionsays the right number but the behavior is old. A version string only changes when a release bumps it, so two builds of the same version — a stalecargo installand a fresh one — report identically. Compare the file itself rather than the version:ls -l "$(which handoff-mcp)" # check the mtimeWhen in doubt, reinstall the binary and restart Claude Code.
Old versions pile up in the plugin cache. Claude Code keeps each installed version in its own directory under
~/.claude/plugins/cache/handoff-mcp-marketplace/<plugin>/<version>/. This is harmless — the active version is recorded in~/.claude/plugins/installed_plugins.json— but you can reclaim the space by deleting the directories for versions you no longer use.
cargo
cargo install handoff-mcpnpm
npm install -g handoff-mcp-serverBoth install the same binary, by different routes. cargo install fetches the
crate from crates.io and compiles it,
so it needs a Rust toolchain and works on any target Rust supports.
npm install downloads a prebuilt binary for your platform and compiles
nothing — see Platform support for the list.
Build from source
git clone https://github.com/alphaelements/handoff-mcp.git
cd handoff-mcp
cargo build --releaseSetup (non-plugin)
If you installed via cargo/npm (without the plugin), register handoff-mcp as an MCP server in Claude Code manually:
Option A — CLI (recommended):
claude mcp add -s user handoff -- handoff-mcpThe -s user flag registers it globally (available in all projects). Verify with claude mcp get handoff.
Option B — Manual edit of ~/.claude.json:
{
"mcpServers": {
"handoff": {
"type": "stdio",
"command": "handoff-mcp",
"args": []
}
}
}Enable automatic memory injection (optional)
If you installed via the plugin, use handoff-mcp-hooks instead (see above).
For non-plugin installs, run:
handoff-mcp setupThis installs Claude Code hooks into ~/.claude/settings.json and adds a
handoff server entry to the project's .mcp.json (required for hooks to
connect). It also prepares the project's CLAUDE.md and records the project's
commands (see Project sections and commands).
The command is interactive by default — use -y to skip prompts:
handoff-mcp setup -y # non-interactive (auto-approve everything)
handoff-mcp setup --mcp-json # only add .mcp.json entry (skip hooks)
handoff-mcp setup --claude-md-scaffold # only add the CLAUDE.md project sections and [commands]
handoff-mcp setup --check # check hooks, .mcp.json, CLAUDE.md and [commands] (see Readiness check)Restart Claude Code after running setup. An argument setup does not know is
rejected (handoff-mcp setup --help lists them).
Project sections and commands
handoff-mcp setup runs in the project directory and, besides the
Session Handoff section, adds the sections the task-loop agents read from
CLAUDE.md: Build & Test, Coding Rules, Project Structure and
Documentation Contract.
- A section counts as present when
CLAUDE.mdhas a heading with that title (any heading level, case-insensitive; headings inside fenced code blocks do not count). A section that is present is never changed; only missing ones are appended, after the existing content. Running setup again changes nothing. - Without a
CLAUDE.md, setup creates one. - Every field setup cannot fill in is marked
TODO(handoff). Replace each marker with the real value, or withn/awhen the project has no such step.
The commands themselves live in the [commands] section of
.handoff/config.toml, which is their source of truth; Build & Test is a
copy for people and agents to read. Setup detects commands from the project's
manifests and writes them to [commands], leaving any key that already has a
value untouched:
| Manifest | Detected |
|----------|----------|
| package.json | build / test / lint / format / typecheck, one per script of that name, as npm run <name> (pnpm / yarn / bun when packageManager or a lockfile says so). The placeholder test script written by npm init is not counted. |
| Cargo.toml | build = cargo build, test = cargo test, lint = cargo clippy, format = cargo fmt |
| pyproject.toml | test = pytest when pytest is configured or listed as a dependency; lint = ruff check . and format = ruff format . likewise for ruff (prefixed with uv run / poetry run when the project has that lockfile) |
When several manifests offer the same key, the first in this order wins.
install, smoke and audit are never guessed. Any other project layout
(a Makefile, Gradle, ...) is not an error: nothing is detected, every field is
marked, and you write the commands yourself:
[commands]
test = "make test"
smoke = "./scripts/smoke.sh"[commands] is only written to a project that is already initialized
(handoff_init). On a project that is not, setup still fills Build & Test
with what it detected; run it again after initializing to record the commands.
You can check the current status or remove the hooks:
handoff-mcp setup --check # Show hook status and the readiness check
handoff-mcp setup --uninstall # Remove handoff hooksThe hooks fire on every prompt and file edit, which adds a small overhead per
interaction. If you want to stop automatic injection, run
handoff-mcp setup --uninstall — the memory tools themselves remain available
for manual use, only the automatic hooks are removed.
See Automatic injection via hooks for the manual configuration alternative.
Quick Start
First project
The handoff-getting-started skill walks you from an empty directory to one
finished task. With the plugins installed (see
Installation; the loop commands come with handoff-task-loop),
open Claude Code in the directory and say "getting started", or type
/handoff-getting-started. Claude then takes you through these steps, telling
you before each one what is about to happen:
| Step | Operation | What you get |
|------|-----------|--------------|
| 1 | Install | The handoff-mcp program and the handoff-mcp and handoff-task-loop plugins |
| 2 | handoff_init(project_name: "<name>", preset: "beginner") | A .handoff/ directory, with the beginner preset applied |
| 3 | handoff-mcp setup | CLAUDE.md with the project sections, and the server entry in .mcp.json |
| 4 | handoff_doctor | The readiness check: what is still missing, and what to do about it |
| 5 | /brainstorm-loop | A brainstorm report: what to build and for whom |
| 6 | /requirement-loop | Requirements with acceptance criteria, and the tasks to work on |
| 7 | /session-loop | Tasks implemented and tested by agents, ending in done |
Lost on the way? handoff_next_step (or handoff-mcp next-step in a terminal)
names the one operation to do next; see Next step.
The session cycle
Adding handoff to work you already do takes only the session cycle:
Initialize a project:
The agent calls
handoff_initwith your project name. This creates a.handoff/directory:.handoff/ ├── config.toml # Project settings ├── sessions/ # Session history (JSON files) └── tasks/ # Task tree (directories + JSON files)Load context at session start — the agent calls
handoff_load_context. Ifsession_guidanceis returned, the agent establishes an active session viahandoff_save_contextwithsession_status: "active"before starting work.Work normally — create tasks, track progress, make decisions. The active session persists on disk, so progress survives interruptions.
Save context at session end — the agent calls
handoff_save_contextto close the active session with handoff data (summary, decisions, blockers, references).
Managing .handoff/ in Git
.handoff/ holds your project's tasks, documents, memory and session history,
which are worth versioning and sharing. It also holds a few machine-local files
(lock files, agent records, timer state, injection caches) that must never be
committed. Pick one of three setups:
| Pattern | How | Good | Watch out for |
|---|---|---|---|
| A. Independent repo (recommended) | Add /.handoff/ to the project's .gitignore, then run git init inside .handoff/ | .handoff/ has its own history; project diffs and reviews stay clean; you can commit handoff state as often as you like | One more repository to back up and push |
| B. Part of the project repo | Commit .handoff/ with the project, and add the recommended .handoff/.gitignore below | One repo, handoff state versioned together with the code | Frequent handoff commits mix into code history; automatically updated files collide when several people or clones work at once |
| C. Not tracked | Add /.handoff/ to the project's .gitignore and do not create a repo for it | Nothing to maintain | Local only: no history, no backup, no sharing |
Recommended .handoff/.gitignore
handoff_init writes this file. On projects that already exist, handoff-mcp
appends any missing line the first time it writes the matching kind of file
(lines you added yourself are kept, nothing is duplicated, and only
.handoff/.gitignore is ever changed — never the project's own repository or
.gitignore).
# Lock files used to serialize concurrent writers (tasks, agents, test runs, brainstorm).
*.lock
# One record per running agent / window; only meaningful on this machine.
/agents/
# Timer state shared with the editor extension on this machine.
/timer/
# Per-session "already injected" records of handoff_memory_query.
/memory/injected/
# Per-session "already injected" records of handoff_doc_query.
/docs/injected/
# Derived cache, rebuilt from the documents and tasks.
/docs/_task_ids_rebuild.json
# Derived cache, rebuilt from the documents.
/docs/_requirements_summary.json
# Derived output of handoff_trace_report.
/docs/_trace_report.json
# Derived cache of the latest recorded test results.
/runs/_latest.json
# Derived index of the trace baselines (the baseline records themselves are tracked).
/trace/baselines/_index.json
# Generated PDFs and their Typst sources.
/exports/
# Transient mermaid render cache used by PDF export.
.mermaid-cache/
# Chart file channel: requests, responses, and rendered output.
/charts/What to track
| Track | Do not track |
|---|---|
| config.toml | *.lock files |
| tasks/ (task records) | agents/, timer/ |
| docs/ (your documents) | docs/injected/, memory/injected/ |
| memory/ (saved memories) | The derived files listed above |
| sessions/, events.jsonl, time_log.jsonl | exports/ (generated PDFs; handoff-mcp warns until it is ignored) |
| runs/, test_runs/, trace/baselines/ (records) | |
| brainstorm/, referrals/, reports/ | |
If lock files or caches are already tracked
Untrack them once (the files stay on disk), then commit:
git -C .handoff rm -r --cached --ignore-unmatch -q -- '*.lock' agents timer memory/injected docs/injected
git -C .handoff commit -m "Stop tracking machine-local handoff files"This works for pattern A and pattern B alike.
Sharing .handoff/ across clones or people
- Do not use a script that runs "add everything, commit and push" on a timer: it sweeps automatically updated files into the commit and is the usual cause of conflicts.
- Run
git pull --rebasebefore every push, and do not use--force. - Keep every clone on the same handoff-mcp version. A binary from v0.47.2 or
earlier that works on the same
.handoff/rewrites files in the old shape: it can drop the sessioncontinueslink and write back the memory usage counters (hit_count,last_referenced_at) that newer versions removed.
Very long task directory names
Task directories are named {task_id}-{slug}. Since v0.47.3 the slug is capped
at 120 bytes, but older versions could create names longer than the 255 bytes
most filesystems allow (typically from long titles written in multi-byte
characters, created on a filesystem that counts characters rather than bytes).
Git can then fail to check such a directory out on Linux, and copying .handoff/
to another filesystem can fail the same way. handoff_load_context reports
the number of affected directories and one example in its warnings.
Rename each one to a shorter name that keeps the {task_id}- prefix; a task is
found by that prefix, and the task file inside is unchanged:
git -C .handoff mv 'tasks/t12-<very long name>' tasks/t12-short-nameFor a subtask, rename the directory inside its parent's directory the same way.
Tools
Core Session Management
| Tool | Purpose |
|------|---------|
| handoff_init | Initialize .handoff/ directory for a project (preset: "beginner" starts with the beginner preset) |
| handoff_load_context | Load session context, tasks, and git state at session start |
| handoff_save_context | Save session state — establish an active session or close it with handoff data |
| handoff_update_session | Incrementally update active session (toggle checklist, add decisions/notes/pointers) |
| handoff_list_sessions | List all sessions (open/active/paused/closed) with summary info |
| handoff_get_session | Get full detail of a specific session by ID |
| handoff_fork_session | Fork a new session from an existing one with context inheritance |
| handoff_merge_sessions | Merge multiple sessions into one with conflict detection |
Task Management
| Tool | Purpose |
|------|---------|
| handoff_list_tasks | List tasks with filters (status, assignee, milestone, priority, label) |
| handoff_get_task | Get full task details (notes, done_criteria, schedule, etc.); include_orphan: true adds orphan (whether the task has no requirement link, by the task_orphan rule) |
| handoff_update_task | Create, update, or move tasks; supports notes_append for safe incremental notes and requirement_ids for linking to requirement SubItems |
| handoff_check_criterion | Toggle a single done_criteria item by index |
| handoff_log_time | Log hours worked — adds to actual_hours, deducts from remaining_hours |
| handoff_bulk_update_tasks | Update multiple tasks in one call (status, schedule, assignee, priority) |
| handoff_task_checklist | Unified view of a task's done_criteria and linked verification matrix items |
Metrics & Scheduling
| Tool | Purpose |
|------|---------|
| handoff_get_metrics | Project metrics: completion %, effort, overdue, budget, milestones |
| handoff_snapshot_metrics | Save today's metrics snapshot (schema v2: metrics plus the task list {id,title,status,assignee,priority}) to .handoff/metrics_snapshots/<YYYY-MM-DD>.json (also taken automatically by handoff_save_context, once per day, overwriting) |
| handoff_get_metrics_snapshot | Restore the task state as of the end of a past UTC day (date): the v2 snapshot of that day when no later change touched it (exact), else the nearest snapshot at or before the day plus replayed task.status_changed events, else an estimate rewound from the current tree. Estimates (exact=false) cannot recover tasks created after the base snapshot that never changed status, nor later title/assignee/priority edits; gaps are listed in warnings. v1 snapshots carry no task list |
| handoff_get_capacity | Work capacity for a date range, respecting calendar and assignee config |
| handoff_auto_schedule | Auto-schedule tasks based on dependencies, estimates, and capacity |
| handoff_events | Query event history from .handoff/events.jsonl (task/session/timer events) |
Configuration & Team
| Tool | Purpose |
|------|---------|
| handoff_get_config | Read project configuration (full TOML as JSON) |
| handoff_update_config | Update config: settings, calendar, assignees, effort budget, gantt view, commands, onboarding; or apply a preset (preset: "beginner") |
| handoff_next_step | Tell which of nine states the project is in (not_initialized ... all_done) and the one operation to do next. Read-only. Not handoff_trace_next, which lists verification items. See Next step |
| handoff_doctor | Diagnose whether the project is ready for agent-driven work (handoff initialized, MCP registered, CLAUDE.md sections filled in, [commands] defined and succeeding, no secrets file tracked by Git, dependency audit passing). Never runs commands: returns commands_to_run and judges the results you report. See Readiness check |
| handoff_release_check | Pre-release check of a milestone: tasks done, no open bugs, requirements verified, tests / smoke / dependency audit passing, no secrets file tracked by Git, and the items a person confirms. Never runs commands: returns commands_to_run, judges the results you report and records them with the confirmations. See Release check |
| handoff_list_assignees | List team members with task counts and effort stats |
| handoff_add_assignee | Add a team member ([assignees.<key>]) |
| handoff_update_assignee | Update a team member's fields (partial; null clears a field) |
| handoff_remove_assignee | Remove a team member and unassign them from every task |
| handoff_list_milestones | List milestones ([milestones.*]) |
| handoff_add_milestone | Add a milestone (date, color, description) |
| handoff_update_milestone | Update a milestone (partial). With [onboarding] release_guard, a move to released consults the release check (see Release guard) |
| handoff_remove_milestone | Remove a milestone |
| handoff_update_calendar | Patch the project [calendar] (work hours, closed days, day_hours, schedule_mode) |
| handoff_update_labels | Set the project-level label vocabulary |
| handoff_start_project | Set started_at and optionally shift all task dates to the project start |
These CRUD tools and the VSCode extension write the same config.toml, so the
GUI and the MCP server stay in full parity. All writes are atomic (temp-file +
rename) so a concurrent reader never sees a partially-written file.
Cross-Project
| Tool | Purpose |
|------|---------|
| handoff_dashboard | Overview of all handoff-enabled projects |
| handoff_import_context | Bulk import tasks and session data from documents |
| handoff_refer | Send a cross-project referral (bug, improvement, request) |
| handoff_list_referrals | List incoming referrals from other projects (summaries only) |
| handoff_get_referral | Fetch one incoming referral in full — details, suggested tasks, done_criteria, context |
| handoff_update_referral | Update referral status (open → acknowledged → resolved) |
Timer Coordination
| Tool | Purpose |
|------|---------|
| handoff_timer_start | Start tracking time for a task — delegates to VSCode extension if alive, otherwise starts MCP fallback timer |
| handoff_timer_stop | Stop the timer and log elapsed hours to actual_hours — delegates to VSCode if alive |
| handoff_timer_get_time | Get current timer state (elapsed, authority, projected total) without stopping |
Brainstorming
| Tool | Purpose |
|------|---------|
| handoff_brainstorm_start | Start a brainstorm session — creates the session state, a deliberation-log doc and a report doc, and initializes the coverage tracker |
| handoff_brainstorm_turn | Record one dialogue turn — appends to the log, mirrors decisions into the report, updates coverage |
| handoff_brainstorm_status | Read the current phase, turn count, coverage, decisions and open questions (restores a session after a restart) |
| handoff_brainstorm_finalize | Write the final report, mark the log complete and close the session |
Project Memory
| Tool | Purpose |
|------|---------|
| handoff_memory_save | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
| handoff_memory_query | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a session_id, suppresses repeats already injected this session |
| handoff_memory_delete | Delete a memory by id (full id or unique prefix) |
| handoff_memory_cleanup | Housekeeping that deletes and rewrites no memory by default: returns near-duplicate clusters and old memories (by updated_at) as review candidates, gc's old injection sidecars; exact duplicates are merged only with apply_exact_merges=true (logged as memory.merged) |
| handoff_memory_strip_usage_stats | Opt-in migration (CLI: handoff-mcp memory strip-usage-stats [--apply]): remove the obsolete hit_count / last_referenced_at keys from existing memory files; dry-run unless apply=true, counts only |
For usage best practices (granularity, scope_paths, conflict handling, cleanup), see skills/handoff-memory/SKILL.md.
See Project Memory below for what it is and how to wire automatic injection.
Multi-Worktree
| Tool | Purpose |
|------|---------|
| handoff_overview | Cross-worktree project overview — agents, claim matrix, worktree map |
| handoff_claim_task | Acquire an exclusive agent lock on a task (prevents concurrent work) |
| handoff_release_task | Release an agent lock on a task |
| handoff_reclaim_task | Forcibly reclaim another agent's task lock |
| handoff_list_agents | List registered agents and their claimed tasks |
User Review Board
A plain Markdown file, .handoff/review_board.md, where the AI puts questions for the user to answer by ticking a checkbox or writing a memo. Open it in any editor or Markdown preview.
| Tool | Purpose |
|------|---------|
| handoff_review_init | Create the board with the default categories (an existing board is left untouched) |
| handoff_review_add | Append an item (### title <!-- rb-id: R-NNN -->, attribute lines, body, checkbox, memo line) to a category |
| handoff_review_list | List all boards with pending/confirmed/total counts |
| handoff_review_read | Read a board's items with status, memos, and image paths |
| handoff_review_update | Check/uncheck items and record memos; validates assignee |
| handoff_review_resolve | Mark a board as resolved; locks it against further changes |
Document Management
| Tool | Purpose |
|------|---------|
| handoff_doc_save | Create or update a document (auto-splits into sections) |
| handoff_doc_get | Read a document — full, meta, or single section |
| handoff_doc_list | List/search documents with BM25 and filters |
| handoff_doc_delete | Delete a document; unlinks from tasks |
| handoff_doc_reassemble | Reconstruct original Markdown from sections, with drift detection |
| handoff_doc_export | Export documents as PDF via Typst (built into release binaries; a plain cargo build uses the Typst CLI) (doc_id / doc_ids / scope filter by layer, doc_type, milestone, tags, task_id, bundle, output_dir, template, include_toc); handoff_report takes format: "pdf" too |
| handoff_doc_update_section | Replace a single section by seq (optimistic locking) |
| handoff_doc_tree | Walk family tree (ancestors/descendants/related) |
| handoff_doc_graph | Visualize inter-document relationships with optional verification status |
| handoff_doc_trace | Trace a document's lineage or dependency chain |
| handoff_doc_query | Context injection — staged full/outline, hook-driven |
| handoff_doc_verify | Verification matrix: generate, check, check_all, skip, sync, set_refs, add_item, set_dev_stage, set_priority, backfill_stable_ids |
| handoff_doc_verify_status | Verification progress summary with optional per-section details |
| handoff_doc_req_status | Requirements progress across documents (by status / priority / category, coverage, per-task coverage) |
| handoff_doc_req_list | List individual requirements with filters (priority, dev_stage, category, tests, task), sorting and paging |
| handoff_doc_req_import | Turn a Markdown requirement tree into requirement items with stable IDs and priorities (dry-run first) |
| handoff_doc_req_scan | Suggest code/test references for requirements by scanning source files for requirement IDs |
| handoff_doc_req_impact | Find requirements affected by changed files (or the current git diff) |
| handoff_doc_analyze | Read-only heuristic scan (import step 1) |
| handoff_doc_import | Atomic bulk write after analysis (import step 3) |
| handoff_trace_record | Record one execution batch (pass/fail/blocked/…) against layer-document items, as a new file under .handoff/runs/ |
| handoff_trace_report | V-model coverage/gap report across every layer document, task links, and recorded runs; also refreshes .handoff/docs/_trace_report.json for editor integrations |
| handoff_trace_slice | Neighborhood view around one task or item (up/down/both the requirement↔verification graph), for progressive-disclosure traversal |
| handoff_trace_history | Every recorded execution result for one item, newest first |
| handoff_trace_baseline | Snapshot the current trace graph's coverage, list/diff past baselines |
| handoff_trace_delta | Change-proposal (delta) lifecycle: create/list/apply/reject a pending bundle of ops for human review |
| handoff_trace_ingest | Parse cargo test --format json JSONL output and record each matched test's result via trace_record |
| handoff_trace_scaffold | Generate one verification-layer item per acceptance-criteria bullet of a source item |
| handoff_trace_suspect | List/clear/baseline the 3 suspect kinds a link/task/result falls into when its upstream definition changed |
| handoff_trace_impact | Read-only impact analysis for a proposed change — never writes anything |
| handoff_trace_lint | Read-only lint over the whole trace graph (structure, tailoring, drift, format rules) |
| handoff_trace_matrix | Read-only coverage/gap matrix for one or more layer documents |
| handoff_trace_tree | Read-only nested view of the requirement tree (decomposition DAG) with per-node state and sub-tree roll-up; filter / depth / fields; CLI trace tree --format json|text |
| handoff_trace_next | Read-only prioritized worklist of V-model items/tasks still needing attention |
| handoff_trace_test_run | Test run definitions and dynamically-computed progress (create/record/progress/list) |
| handoff_trace_propose | Read-only suggestion of existing V-model items covering a task, plus a ready-to-review template for a new one |
| handoff_trace_tasks | Generate one task per V-model item still missing the task role it needs |
| handoff_trace_update | Bulk-mutation entry point over several op kinds (upsert_item, link, unlink, suspect clear, approval, …) in one call |
Documents live in .handoff/docs/ as single _doc.<slug>.md files (YAML
frontmatter + body). Large Markdown is split into sections on save;
handoff_doc_reassemble reconstructs the original with drift detection, and
handoff_doc_query feeds staged (outline-first, then full-text) context to
the agent — the same mechanism that powers the hook-driven injection described
below. handoff_doc_verify provides a verification matrix for tracking
per-section review status, implementation/test references, and staleness
detection after spec changes.
Requirements traceability. Requirement items (sub-items of the verification
matrix) carry a stable ID (e.g. C01-FR-101), priority (P0–P3), development
stage (not_started → in_progress → implemented → tested → verified)
and code/test references. Link a task to requirements with
handoff_update_task(task={id, requirement_ids: [...]}); the link is recorded on
both sides (with an implements/executes role), and the development stage
follows the linked implements tasks' status automatically. Progress is
summarized in .handoff/docs/_requirements_summary.json, which the VS Code
extension reads.
Plan lifecycle automation. Save a document with doc_type="plan" (or let
the server infer it from keywords in the slug/title/tags) to enable cascade
notifications: scaffold_suggestions lists requirements not yet linked to any
task, schedule_stale signals when handoff_auto_schedule should be re-run,
orphaned_tasks reports tasks that lost all requirement links after a
requirement was removed, and baseline_suggestions (from trace_suspect
clear) recommends schedule baseline updates. These are suggestions only —
the server never applies side effects automatically. See the handoff-docs
skill's "Plan Lifecycle Notifications" section for the full workflow.
V-model layer documents. Pass layer to handoff_doc_save (one of
requirement/basic_spec/detailed_spec/acceptance/system_test/
unit_test) to turn a document's Markdown body into the source of truth for
its requirement/verification items — every save re-parses ID-prefixed
headings (REQ-001, SPEC-012, AT-001, …) with refines/verifies/
priority/method/test attributes into the verification matrix. Record
execution results with handoff_trace_record, then get a full
coverage/gap report (handoff_trace_report) or a neighborhood slice around
one task/item (handoff_trace_slice). See the handoff-requirements skill for templates and authoring rules,
and the handoff-trace skill for the workflow.
V-model Traceability (optional)
handoff-mcp can track requirements/design/test coverage as a V-model: six
built-in layers (requirement/basic_spec/detailed_spec/acceptance/system_test/unit_test),
linked by refines/verifies, with lint, suspect/reverify tracking, and
baseline diffs. This is entirely separate from the simpler doc_req_import
freeform-SubItem workflow described above — the two are not combined on a
single document (to move imported requirements into a layer document, see
the handoff-trace skill's references/migration.md).
To get started:
- Pick a profile —
handoff_update_config(updates: {"trace.profile": "standard"}), or add it to.handoff/config.toml:[trace] profile = "standard" - Save a document with
handoff_doc_save(slug="...", title="...", layer="requirement", body="...")— the body's headings (e.g.### REQ-001 <title>) become items automatically. - Use
handoff_trace_lintto check structural issues,handoff_trace_matrixfor a coverage table,handoff_trace_nextfor a prioritized worklist, andhandoff_trace_report/handoff_trace_slicefor derivation graphs.
Requirement tree. Within one layer, items can be decomposed to any depth
with - parent: <id>[, <id>...] (several parents form a DAG), ordered with
- order: / - order@<parent>:, and typed with - kind: leaf|group|decision|select.
Children of a decision (2-way) or select (N-way) carry their branch label
in - condition: <label> / - condition@<parent>: <label>. Intermediate nodes
roll up their leaves' verification and progress; handoff_trace_tree (CLI
trace tree) shows the nested view, and lint reports structural and
missing-label problems.
Orphan tasks. Once a project has a layer document, every task is expected
to trace back to a requirement. handoff_trace_lint reports a task with no
requirement link as a task_orphan warning, with its task_id, title and a
suggested_action: link it with handoff_update_task(task: {id,
requirement_ids: [...]}), or add the label no-trace when it is deliberately
outside traceability. A skipped task, a no-trace task, and a parent task
whose leaves are all linked, no-trace or skipped are not reported. Switch
the rule off with [trace.lint.rules] task_orphan = "off".
| Lint rule | Default | Reports |
|-----------|---------|---------|
| task_orphan | warning | a task with no requirement link (see above) |
| task_unlinked | warning | a task that links a layer document but none of its items |
The full rule table is in the handoff-trace skill (references/lint-rules.md).
[trace] orphan_guard decides what happens when such a task is moved to
review or done with handoff_update_task or handoff_bulk_update_tasks:
| orphan_guard | Effect |
|----------------|--------|
| warn (default) | the change applies and the response carries a Warning [ORPHAN_TASK]: ... line |
| block | the call is rejected and nothing is changed, unless force: true is passed |
| off | no check; the response is the same as without the guard |
It uses the same rule as task_orphan, so a no-trace task, a parent traced
through its children, and every task of a project without a layer document are
never affected. Set it with handoff_update_config(updates: {"trace.orphan_guard": "block"});
any other value is rejected.
handoff_get_task(task_id, include_orphan: true) answers the same question for
one task: its response then carries orphan: true or false. The task-loop
plugin's session-closer uses it: a task that still has no requirement link at
the end of a /session-loop session is closed as review instead of done,
with a Requirement link missing: ... note, and every developer report says in
its ### Requirements addressed section which requirements the work addressed,
or why none applies.
The periodic reports of handoff_report (daily, weekly, monthly,
quarterly, yearly) end with an Orphan Tasks section: how many such
tasks the project has, and the id, title and status of each. It lists the
tasks task_orphan reports, as they are when the report is generated. With no
orphan task the section is left out altogether, so those reports are unchanged.
The other report types (verification, inspection, effort, milestone,
defect, completion) never carry it. A project template gets the section
with {{> orphan_tasks}}; pass data: {"orphan_tasks": null} to leave it out
of one report.
Full guide: the handoff-trace skill (overview, setup, workflow, and
references for every trace tool, config key and lint rule, plus a runnable
end-to-end walkthrough) and the handoff-requirements skill (how to write
items, templates, requirement trees).
Task Data Model
Tasks are stored as a directory tree with status encoded in filenames:
tasks/
├── t1-implement-auth/
│ ├── _task.done.json
│ ├── t1.1-design-schema/
│ │ └── _task.done.json
│ └── t1.2-write-handlers/
│ └── _task.in_progress.json
└── t2-deploy-staging/
└── _task.blocked.jsonStatuses: todo | in_progress | review | done | blocked | skipped
Each task can have:
- Assignee — team member key (matches
[assignees.<key>]in config.toml) - Priority —
low/medium/high - Labels — free-form tags
- Done criteria — checklist items (all must be checked before
donetransition) - Links — URLs to issues, MRs, or docs
- Notes — markdown description
- Schedule —
start_date,due_date,estimate_hours,actual_hours,remaining_hours,milestone,pinned - Dependencies — task IDs this task depends on (circular deps rejected)
Session Context
When saving context, the agent can record:
- Summary — one-line description of what happened
- Decisions — what was decided and why, with confidence levels (
confirmed/estimated/unverified) - Blockers — what's preventing progress
- Checklist — items for the next session
- Handoff notes — categorized as
caution,context, orsuggestion - References — links to files, issues, MRs, wiki pages, or URLs
- Context pointers — specific files and line ranges the next session should look at
- Git state — current branch, recent commits, and dirty files (captured automatically)
handoff_load_context also returns project health diagnostics:
docs_health— document count and warnings (e.g. documents without layer or verification matrix)trace_health— V-model traceability status and warningsrequirements_health— requirement totals by status (not_started/in_progress/implemented/tested), with coverage warnings
These fields let the agent detect potential issues at session start without requiring a separate audit call.
Which tasks handoff_load_context lists
task_tree is compact by default: it holds the tasks that belong to the
session, not every task of the project (a project with 300 todos would
otherwise put tens of kilobytes of todos into every session start). Each listed
task carries a scope_reason:
| scope_reason | Tasks |
|---|---|
| active | in_progress / blocked / review (always all of them) |
| scope | The subtrees named in the task_scope argument (always all of them) |
| previous_session | Unfinished tasks in the previous session's related_task_ids (at most 20) |
| sibling | Unfinished siblings of those (at most 10 per parent, by order) |
| unblocked | todo tasks whose dependencies are all done (at most 10) |
| branch | Tasks named by the branch name or the latest 5 commit subjects (fix/t431-x, t419-t424) |
| milestone | todo tasks of the current milestone (the active milestone with the lowest order, else the one the in_progress tasks belong to) |
| priority | todo tasks without a milestone, by priority, then newest id |
Everything except active and scope shares one budget,
[settings] compact_task_limit (default 40). Ancestors of listed tasks are kept
so the tree stays connected (they have no scope_reason). task_tree_meta
reports what was left out (omitted_total, omitted_by_status,
omitted_without_milestone, truncated) and how to get it; task_summary
always counts every task. To fetch other tasks use handoff_list_tasks; to get
the complete tree exactly as before v0.47.3 pass task_tree: "full"
(handoff-mcp session load --task-tree full). session_guidance.suggested_fields.related_task_ids
lists only work in flight, the previous session's unfinished tasks and your
claimed tasks (at most 20).
Dashboard
handoff_dashboard scans directories for projects with .handoff/ and shows a summary:
## my-project (3 tasks)
- [in_progress] Implement auth (high)
- [todo] Add tests (medium)
- [blocked] Deploy staging (medium)
## other-project (1 task)
- [review] Update README (low)Configuration
.handoff/config.toml:
[project]
name = "my-project"
description = "Project description"
[settings]
# session_prune_limit = 100 # Opt-in: keep at most N closed sessions (default: keep all; heads are never pruned).
# The old `history_limit` is deprecated and ignored since v0.47.3.
done_task_limit = 10 # Max completed tasks to show
compact_task_limit = 40 # Tasks (besides active ones) in handoff_load_context's compact task_tree
auto_git_summary = true # Capture git state automatically
require_estimate_hours = true # Require estimate_hours on leaf tasks (default true)
multi_session = true # Allow multiple active sessions (default true for new projects)
ai_estimate_multiplier = 0.2 # Multiplier turning human estimates into AI-effort hours
# default_estimate_hours = 2.0 # auto_schedule's assumed hours for tasks without an estimate (default 8.0)
# schedule_stale_notice = false # Stop adding `schedule_stale: true` to update_task / doc_save responses (default true)
# layer_missing_notice = false # Stop the DIAG-D001 warning for layer-less spec/design documents (default true)
timer_provider = "auto" # "auto" | "vscode" | "mcp" | "off"
timer_authority_ttl_secs = 30 # Heartbeat freshness TTL for authority.json
timer_idle_timeout_minutes = 10 # Idle pause threshold for MCP fallback timer
[dashboard]
scan_dirs = ["~/pro/"] # Directories to scan for dashboard
[calendar]
work_hours_per_day = 8
closed_weekdays = ["sat", "sun"]
closed_dates = ["2026-12-25"]
open_dates = []
schedule_mode = "auto" # "auto" or "manual"
overwork_limit_percent = 150
work_start_hour = 8 # 0-23 (must be before work_end_hour)
work_end_hour = 20 # 1-24
max_parallel_tasks = 1 # >= 1
[calendar.day_hours]
fri = 4 # Per-weekday hour overrides
[effort_budget]
total_hours = 500 # Total project effort cap
[assignees.alice]
display_name = "Alice Chen"
color = "#4A90D9"
work_hours_per_day = 8
closed_weekdays = [1, 2] # Per-assignee overrides
[assignees.bob]
display_name = "Bob Martinez"
color = "#E74C3C"
work_hours_per_day = 6
[gantt_view]
sort = "start" # start, id, id-desc, status
zoom = "week" # day, week, month
mode = "compare" # plan, actual, compare
[trace]
profile = "standard"
orphan_guard = "warn" # off, warn, block: a task with no requirement link entering review/done
# See `handoff-trace` skill for layers/done_guard/id_prefixes/custom profiles.
[commands] # Project commands; any shell command line. All keys optional.
install = "npm install"
build = "npm run build"
test = "npm run test"
lint = "npm run lint"
format = "npm run format"
typecheck = "npm run typecheck"
smoke = "./scripts/smoke.sh" # One command that shows the app still starts and works
audit = "npm audit" # Dependency audit
[release] # Pre-release check (see Release check)
manual_checks = ["docs_updated", "store_listing"] # Items a person confirms: manual:<name>[commands] is the source of truth for the project's commands; handoff-mcp setup
fills it from the project's manifests (see
Project sections and commands). The MCP server
never runs these commands itself.
All configuration sections can be updated via handoff_update_config with dot-notation keys (e.g., "calendar.work_hours_per_day": 7).
Next step
handoff_next_step() (MCP) and handoff-mcp next-step (terminal) answer "what
should happen next in this project?" with the project's state and one
recommended operation: {state, action: {title, command, reason}, facts}.
The states are checked in this order, and the first that applies is returned:
| # | State | Applies when | Recommended operation |
|---|-------|--------------|-----------------------|
| 1 | not_initialized | the project has no .handoff/ | handoff_init |
| 2 | not_ready | the readiness check (without results) is not ready | what its first failed check says to do |
| 3 | review_pending | a task is in review | confirm that task (handoff_get_task) |
| 4 | in_progress | a task is in_progress, or a session is active | resume it |
| 5 | no_brainstorm | no finalized brainstorm report and no requirement item | /brainstorm-loop |
| 6 | no_requirements | the requirement layer has no item | /requirement-loop |
| 7 | ready_tasks | a todo task whose dependencies are all done or skipped | /session-loop |
| 8 | release_ready | no unfinished task, and a milestone that is neither released nor cancelled | handoff_release_check (see Release check) |
| 9 | all_done | none of the above | plan what comes next (/brainstorm-loop); when unfinished tasks remain that cannot start, clear what blocks them |
action.commandis a slash command, a tool call or a sentence to act on.factsholds the counts the decision looked at (doctor,tasks,active_sessions,brainstorm_reports,requirement_items,milestones). A group the decision did not need is left out.- The tool is read-only: it writes nothing, runs no command and starts no process. It works on a project that is not initialized yet.
- With
[onboarding] next_step = true,handoff_load_contextcarries the same answer as itsnext_stepkey. Without the setting the key is absent and the response is unchanged. handoff_trace_nextis a different tool: it lists the verification items of the trace graph that still need attention.
Readiness check
handoff_doctor (MCP) and handoff-mcp setup --check (terminal) give the same
diagnosis of whether the project is ready for the task loop:
| Check | Passes when |
|-------|-------------|
| handoff_initialized | .handoff/config.toml exists and can be read |
| mcp_registered | a handoff server entry is found in .mcp.json, ~/.claude/settings.json, ~/.claude.json, the Claude Code plugin list or ~/.codex/config.toml (skip when none is found: other clients are not inspected) |
| claude_md_sections | CLAUDE.md has the four project sections |
| claude_md_todo | no TODO(handoff) marker is left in CLAUDE.md |
| commands_defined | [commands] defines at least one command |
| cmd_install / cmd_build / cmd_test / cmd_lint / cmd_typecheck | that command ran with exit code 0 |
| smoke_defined | [commands] smoke is defined (skip, never a failure, when it is not) |
| secrets_untracked | Git tracks no file whose name matches a secrets pattern (skip outside a Git repository). See Secrets files and the dependency audit |
| dependencies_audited | [commands] audit ran with exit code 0 (skip when it is not defined or no result was given) |
Each check is pass, fail or skip (manual, a person has to confirm, is
part of the same vocabulary for the release check). skip means the check was
not carried out and is never counted as a pass. Every fail comes with a
next_step. The project is ready when nothing failed.
Commands are only run when you ask for it, and never by the MCP server:
handoff_doctor()returns the defined commands incommands_to_run({id, command, timeout_sec}) and marks their checksskip. The agent runs them and calls again withresults: [{id, command, exit_code?, duration_ms?, output_tail?, error?}]; the tool judges those (source: "reported"). A result for a command that is not the current[commands]value is not used and fails the check. A call with an argument or result field the tool does not know, or with an emptyerror, is rejected instead of being judged.handoff-mcp setup --check --runruns the commands itself, in the project directory, through the shell (sh -c;cmd /Con Windows), and judges the results (source: "executed"). A command that cannot be found, or that runs longer than[onboarding] command_timeout_sec(default 600), fails. It runsinstall,build,test,lint,typecheckandaudit;formatandsmokeare not run.- Once commands were run, a project without
[commands] testis not ready.
handoff-mcp setup --check prints the hook status followed by the diagnosis;
add --json to print only the JSON that handoff_doctor returns. The exit code
is 0 when the project is ready and 1 when it is not.
Secrets files and the dependency audit
Two checks are shared by the readiness check and the release check:
secrets_untrackedfails when Git tracks a file whose name matches one of.env,.env.*,*.pem,*.key,id_rsa,id_ed25519,credentials.jsonorsecrets.*, in any directory..env.example,.env.sampleand.env.templateare never reported. Thedetaillists the matching paths.- Only file names are matched. File contents are not scanned, so a
passdoes not mean the repository holds no secret. - The list of tracked files is read from the Git index file;
gitis not started. Outside a Git repository, or when the index cannot be read completely (a split or sparse index), the check isskip. - A project in a subdirectory of a larger repository is checked for its own files.
- Replace the patterns with
[onboarding] secret_file_patterns = ["*.tfstate", ...].*matches any run of characters and?one; letter case is ignored. A pattern without/applies to the file name in every directory, one with/to the whole path. An empty list switches the check toskip.
- Only file names are matched. File contents are not scanned, so a
dependencies_auditedjudges the result of[commands] audit(for examplenpm auditorcargo audit), handed out incommands_to_runand judged like the other commands. Itsdetailquotes the end of the command's output (up to 20 lines). It isskipwhen the command is not defined or no result was given, never a pass.
Release check
handoff_release_check(milestone) (MCP) and
handoff-mcp release-check <milestone> (terminal) answer one question before a
milestone ships: is everything it promised done, verified and safe to release?
| Item | Passes when |
|------|-------------|
| tasks_done | every leaf task of the milestone is done or skipped (refs lists the others). A subtask without a milestone of its own belongs to its parent's |
| no_open_bugs | no task of the milestone labelled bug is still open |
| requirements_verified | every requirement-layer item planned for the milestone is passing (refs lists the others; skip when the milestone has no requirement) |
| tests_pass / smoke_pass | [commands] test / smoke ran with exit code 0 |
| secrets_untracked / dependencies_audited | see Secrets files and the dependency audit |
| manual:<name> | a person confirmed it; one item per entry of [release] manual_checks (manual until then) |
The answer is {milestone, ok, items: [{id, status, detail, refs?, source?,
checked_at?}], commands_to_run}. ok is true only when every item is
pass: an item that was skipped (not carried out) or still waits for a person
keeps it false, so a project without a smoke command, an audit command or
requirements for the milestone does not get ok: true.
As with the readiness check, the MCP tool never runs a command:
handoff_release_check(milestone: "v1.0")reports the command items asskipand lists the defined commands incommands_to_run.- The agent runs them and calls again with
results(the same shape as forhandoff_doctor, with the idstests_pass,smoke_pass,dependencies_audited). - When a person has confirmed a manual item, pass
confirm: ["manual:docs_updated"]. It stays confirmed for that milestone.
Results and confirmations passed in are recorded in
.handoff/release/<milestone>.json (per command: status, exit code, who ran it,
when). A call with neither writes nothing. A call without results never falls
back on a recorded result: those items are skip again, so an old run cannot
make today's check pass. An unknown milestone is an error.
In a terminal:
handoff-mcp release-check v1.0 # print the check as JSON
handoff-mcp release-check v1.0 --run # also run test / smoke / audit and judge them
handoff-mcp release-check v1.0 --confirm manual:docs_updated # record a confirmationThe exit code is 0 when the check is ok, 1 when it is not, and 2 when it could
not be carried out (a usage error, an unknown milestone).
Release guard
[onboarding] release_guard puts the release check in front of the moment a
milestone becomes released
(handoff_update_milestone(name, status: "released"),
handoff-mcp milestone update --name <name> --status released):
| release_guard | When an item of the check is not pass |
|-----------------|------------------------------------------|
| off (default) | Nothing is checked. The reply is the same as without the setting |
| warn | The milestone is released, and the reply lists the items: one Warning: release check: <id> [<status>] <detail> line each |
| block | The call is rejected with the same list and nothing changes. force: true releases anyway, with the items as warnings |
Releasing a milestone never runs a command. The items that follow from the
project's data (tasks_done, no_open_bugs, requirements_verified,
secrets_untracked, manual:<name>) are judged on the spot. The command items
(tests_pass, smoke_pass, dependencies_audited) are read from the last
result recorded in .handoff/release/<milestone>.json; without a record, or
when [commands] has changed since, the item counts as not verified (skip).
Because a record may be out o
