/handoff

name: handoff
description: Build and consume handoff artifacts for multi-agent work. Use when switching between Claude, Codex, Cursor, or other AI agents.

Multi-Agent Handoff

Building a handoff

codemap handoff .                 # Build + save full artifact
codemap handoff --json .          # Machine-readable for other tools
codemap handoff --prefix .        # Stable context only (hubs, configured file count)
codemap handoff --delta .         # Recent work only (changed files, risk, events)

What's in a handoff

• **Prefix** (stable): configured project file count, hub summaries, changes rarely
• **Delta** (dynamic): changed files, risk files, recent edit events, next steps
• **Hashes**: deterministic hashes for cache validation across agents

Consuming a handoff

codemap handoff --latest .        # Read most recent saved artifact
codemap handoff --detail file.go . # Lazy-load full context for one file

The MCP tool `get_handoff` provides the same capabilities for tool-based consumption. The prefix file count and size-based handoff budgets honor the active `.codemap/config.json` filters even when watch state tracks a broader working set.

When to handoff

• Switching from Claude to Codex (or vice versa)
• Starting a new Claude session on the same branch
• Context window getting full: compact and resume
• Passing work to a teammate's AI session

Artifacts written

| File | Content | |------|---------| | `.codemap/handoff.latest.json` | Full artifact (all layers) | | `.codemap/handoff.prefix.json` | Stable prefix snapshot | | `.codemap/handoff.delta.json` | Dynamic delta snapshot | | `.codemap/handoff.metrics.log` | Append-only metrics stream |