Here is a summary of everything new in Handoff MCP from v0.21 through v0.26. The highlights are full document lifecycle management, significantly better memory search for Japanese text, a smoother setup experience, and official Codex CLI support.

Document Management (v0.21–v0.25)

Specs, design docs, and ADRs can now be managed directly inside .handoff/.

Storage and Tools

YAML frontmatter single-file format — metadata and content live in one .md file per document, replacing the previous split JSON + content model. Existing data migrates automatically on first access.
doc_update_section — update a single section by heading path without rewriting the entire body.
doc_graph — returns all managed documents as a graph with nodes, edges (parent/child, related links, implicit shared-task connections), and layers grouped by document type.
doc_trace — traces a document's lineage chain upstream and downstream, detecting forks and cycles.
append_body — append new sections to an existing document without a full rewrite.
suggest_refs — scans project source files and suggests relevant cross-references for a document heading.

Verification Matrix

Track review progress at the section level.

doc_verify — mark each section heading as checked, skipped, or flagged with notes and code references. sync reconciles items after document edits.
doc_verify_status — query verification progress (total, checked, unchecked, skipped) without modifying state.
task_checklist — unified readiness view combining a task's done_criteria with linked document verification progress. The generate action auto-creates done_criteria from a spec's section headings.

Search Quality Improvements (v0.24.7–v0.24.9)

Memory and document search switched to weighted BM25, substantially improving Japanese text retrieval.

Weighted BM25 — Japanese case particles (ha, ga, wo, de, ni, …) now boost the content words they mark, and stopwords plus CL-CnG trigrams are excluded from corpus statistics. MRR improved from 0.923 to 0.936 on a real 35-memory, 13-query evaluation set.
Relative threshold filter — candidates scoring below a fraction of the top score are dropped, preventing low-relevance "tail noise" from riding a strong top hit.
min_score raised from 0.1 to 2.0 — aligned with the weighted BM25 scale. False-positive injections from unrelated prompts dropped significantly.
lexsim 0.7.0 — explicit TF boost for document-side keywords and restored content-derived trigram weighting.

Streamlined Setup (v0.24.3–v0.24.5)

The handoff-mcp setup command got a major upgrade.

Automatic .mcp.json configuration — adds the handoff server entry to your project's .mcp.json. Use --mcp-json to add only the entry without touching hooks.
--global flag — installs to ~/.claude/settings.json for a machine-wide setup.
CLAUDE.md template injection — appends a "Session Handoff" section with lifecycle instructions to your project's CLAUDE.md. --force updates an existing section.
Enhanced --check — reports hooks, .mcp.json, and CLAUDE.md status in one view.

Session Management Improvements (v0.22–v0.24.6)

session-loop v2 — simplified to three serial stages (implement → test → review), reducing agent spawns from up to 26 to 8 per session.
Session field preservation — save_context no longer overwrites accumulated fields (decisions, handoff_notes, etc.) when they are not explicitly provided.
Safe multibyte truncation — fixed a panic when truncating Japanese text by byte position instead of character count.
Weekday name support in read_config — the custom deserializer now accepts ["sun", "sat"] as written by the VSCode extension, in addition to numeric values.

Codex CLI Support (v0.26)

The Handoff MCP plugin now works with OpenAI's Codex CLI in addition to Claude Code.

agents/openai.yaml — all six skills include Codex UI metadata (display_name, short_description, default_prompt) and MCP tool dependency declarations.
AGENTS.md — a session handoff instructions template for Codex users. Copy it into ~/.codex/AGENTS.md to enable automatic session management.

Other Fixes

npm source build fix (v0.25.1) — templates/ was missing from the npm package, causing cargo build to fail on platforms without a prebuilt binary.
Hooks plugin stabilization (v0.24.1–v0.24.4) — fixed MCP server name resolution and hook operation without .mcp.json.
estimate_hours rule relaxed (v0.23) — leaf tasks in todo no longer require an estimate. The requirement is enforced when moving to in_progress or later.

Install / Update

npx handoff-mcp-server@latest

If you are using the Claude Code plugin:

/plugin install alphaelements/handoff-mcp

View Handoff case studies