npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

handoff-mcp-server

v0.49.0

Published

MCP server that gives AI coding agents persistent memory across sessions

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-mcp

Confirm the plugin and MCP server, then begin a new Codex session:

handoff-mcp --version
codex plugin list
codex mcp get handoff

Use $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-loop and /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-plugins

This 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-mcp is the plugin name; handoff-mcp-marketplace is the marketplace name (the name field 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=optional skips 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-mcp on 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-plugins

Adds /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-plugins

This 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 handoff MCP server entry in the project's .mcp.json. Run handoff-mcp setup --mcp-json in 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-loop and handoff-mcp-hooks plugins ship with defaultEnabled: false, so they need an explicit /plugin enable step after install. The main handoff-mcp plugin is defaultEnabled: true and 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-plugins

After 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 Code

Update 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-marketplace

Steps 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 marketplace

claude 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/cache and 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 your PATH (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-mcp earlier on your PATH shadows the new one. This is the most common cause of "I updated and nothing changed", because npm install -g and cargo install write 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)"
    done

    The 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 your PATH.

  • --version says 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 stale cargo install and a fresh one — report identically. Compare the file itself rather than the version:

    ls -l "$(which handoff-mcp)"   # check the mtime

    When 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-mcp

npm

npm install -g handoff-mcp-server

Both 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 --release

Setup (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-mcp

The -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 setup

This 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.md has 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 with n/a when 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 hooks

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

  1. Initialize a project:

    The agent calls handoff_init with your project name. This creates a .handoff/ directory:

    .handoff/
    ├── config.toml      # Project settings
    ├── sessions/        # Session history (JSON files)
    └── tasks/           # Task tree (directories + JSON files)
  2. Load context at session start — the agent calls handoff_load_context. If session_guidance is returned, the agent establishes an active session via handoff_save_context with session_status: "active" before starting work.

  3. Work normally — create tasks, track progress, make decisions. The active session persists on disk, so progress survives interruptions.

  4. Save context at session end — the agent calls handoff_save_context to 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 --rebase before 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 session continues link 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-name

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

  1. Pick a profile — handoff_update_config(updates: {"trace.profile": "standard"}), or add it to .handoff/config.toml:
    [trace]
    profile = "standard"
  2. Save a document with handoff_doc_save(slug="...", title="...", layer="requirement", body="...") — the body's headings (e.g. ### REQ-001 <title>) become items automatically.
  3. Use handoff_trace_lint to check structural issues, handoff_trace_matrix for a coverage table, handoff_trace_next for a prioritized worklist, and handoff_trace_report/handoff_trace_slice for 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.json

Statuses: 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 done transition)
  • 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, or suggestion
  • 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 warnings
  • requirements_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.command is a slash command, a tool call or a sentence to act on.
  • facts holds 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_context carries the same answer as its next_step key. Without the setting the key is absent and the response is unchanged.
  • handoff_trace_next is 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 in commands_to_run ({id, command, timeout_sec}) and marks their checks skip. The agent runs them and calls again with results: [{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 empty error, is rejected instead of being judged.
  • handoff-mcp setup --check --run runs the commands itself, in the project directory, through the shell (sh -c; cmd /C on 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 runs install, build, test, lint, typecheck and audit; format and smoke are not run.
  • Once commands were run, a project without [commands] test is 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_untracked fails when Git tracks a file whose name matches one of .env, .env.*, *.pem, *.key, id_rsa, id_ed25519, credentials.json or secrets.*, in any directory. .env.example, .env.sample and .env.template are never reported. The detail lists the matching paths.
    • Only file names are matched. File contents are not scanned, so a pass does not mean the repository holds no secret.
    • The list of tracked files is read from the Git index file; git is not started. Outside a Git repository, or when the index cannot be read completely (a split or sparse index), the check is skip.
    • 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 to skip.
  • dependencies_audited judges the result of [commands] audit (for example npm audit or cargo audit), handed out in commands_to_run and judged like the other commands. Its detail quotes the end of the command's output (up to 20 lines). It is skip when 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:

  1. handoff_release_check(milestone: "v1.0") reports the command items as skip and lists the defined commands in commands_to_run.
  2. The agent runs them and calls again with results (the same shape as for handoff_doctor, with the ids tests_pass, smoke_pass, dependencies_audited).
  3. 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 confirmation

The 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