handover

Design in chat. Build in terminal. Zero context lost.

handover is an open-source CLI tool that bridges AI chat interfaces (Claude, ChatGPT, Gemini, and others) to local terminal coding agents (Claude Code, Codex CLI, Copilot, Aider, Goose, etc.). It extracts decisions, plans, and intent from a chat conversation and generates agent-specific handover artifacts — the exact files each coding agent expects — so a local agent can immediately act on your intent without re-explaining anything.

Each target adapter knows what its agent needs: Claude Code gets CLAUDE.md + PLAN.md, Codex gets AGENTS.md + TASKS.md, Copilot gets .github/copilot-instructions.md, and so on. The parsing and extraction happen once; each target decides how to express the result.

Install

pip install handover

Optional extras:

pip install 'handover[watch]'   # enables: handover watch (session file monitoring)
pip install 'handover[mcp]'     # enables: handover mcp (MCP server for Claude Code)

zsh users: the brackets must be quoted. Unquoted pip install handover[watch] fails with zsh: no matches found because zsh interprets [...] as a glob.

Quickstart

# Basic usage — single conversation file
handover --input conversation.json --output ./my-project/

# List all conversations in a bulk export
handover list export.jsonl

# Bulk export — select a specific conversation by title
handover --input export.jsonl --title "API Design Discussion" --output ./my-project/

# Incremental update — merge new context into existing .handover/ (v1.2.0)
handover update --input follow-up.json --output ./my-project/

# Sync backlog task status from codebase evidence (v1.2.1)
handover sync --project ./my-project/

# List conversations grouped by project (v1.2.0)
handover list export.jsonl --by-project

# Merge conversations by project name (v1.2.0)
handover merge --input export.jsonl --project "API Design" --output ./my-project/

--dry-run Demo

$ handover --input chat.json --output ./my-project/ --no-llm --dry-run

Parsing: 'API Design Discussion'
  Source : claude (single-json v1.0)
  Messages: 34

Extracted:
  Goal       : Build a FastAPI REST API with JWT auth and PostgreSQL
  Tech Stack : Python, FastAPI, PostgreSQL, pytest
  Decisions  : 2
  Tasks      : 6
  Constraints: 2
  Questions  : 1

Target: claude-code  |  Would write to ./my-project/:
  -> CLAUDE.md
  -> PLAN.md

Run without --dry-run to write files.

Supported Input Formats

Two-Layer Output (v1.1.0)

Every run produces two layers:

1. .handover/ — vendor-neutral knowledge base (always generated): manifest, context (overview, architecture, ADR-style decisions, constraints, risks, acceptance criteria), work plan (spec, tasks, milestones, backlog JSON), standards, and 6 drop-in prompts. Portable across any agent.
2. Per-target workspace — for claude-code, a thin CLAUDE.md index plus .claude/agents, .claude/skills, .claude/commands, .claude/hooks, and settings.json, populated by domain detection on the chat.

your-project/
├── .handover/
│   ├── manifest.yaml
│   ├── context/   overview.md, architecture.md, decisions.md, ...
│   ├── work/      spec.md, tasks.md, milestones.md, backlog.json
│   ├── standards/ coding-standards.md, testing-standards.md, ...
│   ├── prompts/   implement.md, review.md, debug.md, ...
│   └── codebase/  structure.json, symbols.json, dependencies.json, index.md
├── .claude/
│   ├── agents/    backend-agent.md, database-agent.md, ...
│   ├── skills/    rest-conventions.md, ...
│   ├── commands/  run-tests.md, lint.md
│   ├── hooks/     pre-tool-use.sh
│   └── settings.json
├── CLAUDE.md      (thin index pointing into .handover/)
└── PLAN.md

Skip Layer 1 with --no-handover-dir, write only Layer 1 with --handover-dir-only, replace existing layers with --overwrite-handover-dir. See docs/handover-directory.md for the full layout and how to extend it.

Agent-Aware Output

handover parses your chat once and generates the files your chosen coding agent expects. Each target adapter owns its own filenames and format — Claude is one target, not the default mental model for the whole product.

handover --input chat.json --output ./my-project/ --target codex
handover --input chat.json --output ./my-project/ --target copilot
handover --input chat.json --output ./my-project/ --target all

CLI Reference

Chat export → agent context

handover --input <file> --output <dir> [OPTIONS]

Incremental update (v1.2.0)

Update an existing .handover/ directory with new conversation context — preserves completed task marks and manual edits.

handover update --input follow-up.json --output ./my-project/
handover update --input follow-up.json --output ./my-project/ --no-llm --dry-run
handover update --input follow-up.json --output ./my-project/ --no-conflict  # no conflict markers

Explore exports

handover list <export_file>            # list all conversations in a bulk export
handover list export.jsonl --source claude
handover list export.jsonl --by-project  # group by project (v1.2.0)

Scaffold custom templates

handover init       # copies default templates to ~/.handover/templates/ for editing

Reverse handover — Claude Code session → HANDOVER.md

Generates HANDOVER.md from Claude Code session logs: what was accomplished, files changed, decisions made, and recommended next steps.

handover reverse --project .                          # auto-discover latest session
handover reverse --session ~/.claude/projects/…/abc.jsonl
handover reverse --project . --no-llm --dry-run

handover sessions                                     # list recent Claude Code sessions
handover sessions --project ~/my-app --limit 20

handover watch --project .                            # auto-generate when session goes idle
handover watch --project . --idle 30 --daemon         # background mode
# requires: pip install handover[watch]

Local bridge for browser extension

Starts an HTTP server that the Chrome/Firefox extension uses to send conversations directly from the browser.

handover serve                                   # port 7437 (H-A-N-D on phone keypad)
handover serve --port 7437 --output ~/my-app/
handover serve --no-llm --daemon                 # background mode

Endpoints: GET /health, POST /handover, POST /config
See docs/browser-extension.md for extension setup.

History & re-run

Every successful non-dry-run invocation is logged to ~/.handover/history.jsonl.

handover history                          # last 20 runs
handover history --limit 50
handover history --project ~/my-app/     # filter by output directory

handover rerun h_4a2955ab                # re-run a past handover by ID

Merge multiple exports

Combine two or more chat sessions into one unified CLAUDE.md + PLAN.md. Deduplicates tasks and decisions automatically.

handover merge --input session1.json --input session2.json --output ./my-project/
handover merge --input s1.json --input s2.json --output . --no-llm --target all
handover merge --input export.jsonl --project "API Design" --output ./my-project/  # v1.2.0

Share via GitHub Gist

# Publish after generating (requires gh CLI authenticated)
handover --input chat.json --output ./my-project/ --publish

# Pull shared handover artifacts
handover pull https://gist.github.com/user/abc123
handover pull abc123 --output ./my-project/

MCP server for Claude Code

Exposes handover as an MCP server so Claude Code (or any MCP client) can call it directly. Since v1.1.1 the server exposes four tools.

handover mcp
# requires: pip install handover[mcp]

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "handover": {
      "command": "handover",
      "args": ["mcp"],
      "env": { "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    }
  }
}

Full reference: docs/mcp-server.md.

Roadmap

Contributing

The primary contribution path is adding a new source adapter or output target. Each adapter is an isolated Python class anyone can own end-to-end.

• docs/adding-an-adapter.md — add a new chat source (e.g. Mistral, Grok)
• docs/adding-a-target.md — add a new agent target
• CONTRIBUTING.md — general contribution guidelines

License

MIT © 2026 Mohan Krishnaa Alavala