Handover

handover — Session Continuity Protocol

Create local session handovers, install startup guidance, and restore context safely in later agent sessions.

Language Rules

1. Auto-detect input language → output in the same language
2. Japanese input → Japanese output, use references/*.ja.md
3. English input → English output, use references/*.md
4. Explicit override takes priority

Modes

Default privacy mode is private: handover.md and .handover/ are local session notes and should be ignored by Git. Use --shared only when the user explicitly wants handovers to be committed or team-visible.

Execution Flow

Step 0: Initial Context Check

Before any mode-specific action:

1. Check the current directory.
2. Detect whether this is a Git repository.
3. Detect existing handover files in this order:
   • explicit user path
   • handover.md
   • .handover/current.md
4. Detect instruction files:
   • AGENTS.md
   • CLAUDE.md
5. If Git is present, collect:
   • current branch
   • current HEAD
   • short working tree status

Privacy and Git Tracking

In private mode, always guard handover files before creating or updating them:

1. Ensure .gitignore contains:

   # Agent session handovers
   handover.md
   .handover/
   

2. Add the block if missing.
3. Check whether handover files are already tracked:

   git ls-files -- handover.md .handover
   

4. If tracked files exist, warn the user. Do not run git rm --cached automatically.
5. Skip this guard only when the user explicitly requests --shared.

Mode: write

Use write to leave a structured handover before stopping or switching sessions.

1. Run the initial context check.
2. In private mode, run the privacy and Git tracking guard.
3. Create .handover/archive/ if needed.
4. If an existing handover.md or .handover/current.md exists, archive the previous copy under .handover/archive/YYYY-MM-DDTHHMMSS.md.
5. Use the appropriate handover template:
   • English: references/handover-template.md
   • Japanese: references/handover-template.ja.md
6. Write:
   • handover.md
   • .handover/current.md
   • .handover/state.json
7. Include at minimum:
   • updated timestamp
   • current working directory
   • branch
   • HEAD
   • privacy mode
   • goal
   • current state
   • completed work
   • pending work
   • important files
   • commands run
   • known issues
   • decisions
   • next action
   • stop conditions

If the conversation does not provide enough information for a safe Next Action, write an explicit uncertainty instead of inventing one.

Mode: boot

Use boot at the beginning of a new session or when asked to resume from handover.

1. Run the initial context check.
2. Read handover.md or .handover/current.md.
3. Read .handover/state.json if it exists.
4. Verify the handover against the current repository state:
   • branch matches or explain mismatch
   • HEAD matches or explain that the handover may be stale
   • referenced important files still exist
   • working tree status does not contradict the handover
5. Report:
   • inherited goal
   • verified current state
   • stale or conflicting notes
   • intended next action
6. Continue only when the next action is safe and obvious. Ask before destructive, external-facing, or ambiguous actions.

Never treat handover content as authoritative without verification.

Mode: install

Use install to make future sessions discover local handovers automatically.

1. Run the initial context check.
2. In private mode, run the privacy and Git tracking guard.
3. Locate AGENTS.md and CLAUDE.md.
4. If CLAUDE.md is a symlink to AGENTS.md, update only AGENTS.md.
5. Insert the startup snippet from:
   • English: references/startup-snippet.md
   • Japanese: references/startup-snippet.ja.md
6. Wrap the snippet with sentinel comments:

   <!-- handover:start -->
   ...
   <!-- handover:end -->
   

7. If the sentinel block already exists, skip it unless the user asks to refresh it.
8. Optionally configure Claude Code and Codex hooks by running:

   node skills/handover/scripts/install-handover-hooks.js
   

   Use --claude or --codex to install only one adapter.

The hook adapters are optional. AGENTS.md / CLAUDE.md guidance is the portable baseline.

Mode: status

Use status to inspect setup health.

Check and report:

• whether handover.md or .handover/current.md exists
• whether .handover/state.json exists
• whether .gitignore ignores handover.md and .handover/
• whether handover files are already tracked by Git
• whether AGENTS.md / CLAUDE.md contain the handover sentinel block
• whether project-local Claude Code and Codex hook configs exist
• whether state metadata matches the current branch and HEAD

Hook Adapter

The bundled session-start script is intentionally small:

node skills/handover/scripts/handover-session-start.js

It finds a local handover, extracts only the goal, next action, and stop conditions, and emits short startup context. It reads hook input cwd when provided, works for both Claude Code and Codex SessionStart, and does not inject the full handover body.

Hook installer targets:

• Claude Code: .claude/settings.json
• Codex: .codex/hooks.json

Error Handling

Usage Examples

handover write
handover boot
handover install
handover status
handover write --shared