🔁 Agent Handoff Kit

Your AI agents have amnesia. This is the cure.

Rate-limited at hour five? Switch agents. Lose nothing.

中文版 · Quick Start · How It Works · Hooks

---

😵 The problem

Every AI coding agent keeps its brain in its own session. You hit a quota wall, switch tools — and the new agent knows nothing:

Agent A (5 hours in):  "…decided against jsonwebtoken, fixed the row-lock race,
                        verified Phase 2, next up is the adopt endpoint—"
                       💀 [rate limited]

Agent B (fresh):       "Hi! How can I help you today?"
                       🧠 context: ∅

Re-explaining costs thousands of tokens. Details still get lost. Decisions get re-litigated. Pitfalls get stepped on again.

🎯 Why this exists

Multi-agent development is no longer an edge case — it's the default. Rate limits, quotas, and different tools' strengths mean serious projects now rotate between agents as a matter of course. But the tooling hasn't caught up:

• Context is the most expensive asset in AI-assisted development — and the most fragile. Hours of decisions, verifications, and hard-won pitfalls live inside one vendor's session memory, locked to one tool.
• Built-in session resume only works within the same app. The moment you switch — which is exactly when you need it most — you're on your own.
• Exporting transcripts doesn't scale. A full conversation dump costs more tokens to re-ingest than it saves, and buries the signal in noise.

Our goal: make handoff a first-class, file-based convention. Vendor-neutral (works with any agent that can read a file), version-controlled (diffable, reviewable, travels with the repo), cheap (~300 tokens vs thousands for re-explaining), and self-maintaining (the protocol obliges agents to keep it current). Not a new platform, not a sync service — just a small set of files and conventions any project can adopt in five minutes.

💡 The idea

Move context out of session memory and into files inside the repo — the one place every agent can read:

┌─────────────┐   types "handoff"   ┌──────────────────┐
│  Agent A    │ ──────────────────► │   HANDOFF.md     │
│ (any tool)  │                     │  status · next   │
└─────────────┘                     │  pitfalls · env  │
                                    └────────┬─────────┘
┌─────────────┐   reads before code          │
│  Agent B    │ ◄────────────────────────────┘
│ (any tool)  │   ⚡ up to speed in 30s, ~300 tokens
└─────────────┘

• HANDOFF.md — a ≤100-line handoff sheet: current status, next steps, pitfalls, environment cheat sheet. Conclusions + pointers only.
• AGENTS.md — the handoff protocol: "read HANDOFF.md before touching code" + "on the trigger word, maintain the handoff docs". Already the de-facto standard most coding agents load automatically.
• Hooks (optional) — hard-guarantee the trigger word even after a long session compacts AGENTS.md away, and log a git snapshot at every session end.

🚀 Quick start

One-liner (recommended) — installs templates + symlinks, skips existing files:

bash scripts/init.sh /path/to/project zh --copilot   # or: en

Or by hand:

# 1. Drop the templates into your project root
cp templates/en/AGENTS.md templates/en/HANDOFF.md /path/to/project/
cp -r templates/en/.github /path/to/project/        # Copilot support (optional)

# 2. Point every agent's instruction file at one source of truth
cd /path/to/project
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

# 3. Fill in the <placeholders>. Done.

# 4. (Optional) Install the hooks — see hooks/README.md

🇨🇳 Chinese templates live in templates/zh/ (trigger word 「交接」).

🎮 Daily usage

Moment	You do	The agent does
Switching apps	type handoff	pauses, updates HANDOFF.md + progress file, reports in 3–5 sentences
Opening the new app	just start working	reads HANDOFF.md before writing code (enforced by AGENTS.md)

That's it. Two files, one trigger word, zero re-explaining.

🧰 What each tool gets

Tool	Protocol	Trigger word	Auto git snapshot
Kimi Code	✅ native	✅ hard hook	✅ SessionEnd hook
Claude Code	✅ CLAUDE.md symlink	✅ hook	✅ SessionEnd hook
Codex	✅ native	✅ via protocol	—
Gemini CLI	✅ GEMINI.md symlink	✅ via protocol	—
Copilot (VS Code)	✅ native + instructions	✅ /handoff prompt file	—
Copilot coding agent ☁️	✅ native (needs push)	✅ via protocol	—

No hooks? No problem. The AGENTS.md protocol loads into every session anyway — hooks are body armor, not the skeleton.

🧠 Design principles

1. Conclusions + pointers, never transcripts. rewrote token refresh in src/auth.ts (a1b2c3) — not pasted code. The next agent reads the code itself: cheaper and fresher.
2. Single source of truth. The protocol lives in AGENTS.md; everything else is a symlink or a pointer.
3. ~100 lines, hard cap. These files load into every session. Every line costs tokens forever.
4. Self-maintaining. Agents must sync the docs when they change structure, commands, or workflows. Stale docs are worse than no docs.

📁 Repository layout

templates/
  zh/                        🇨🇳 trigger word 「交接」
  en/                        🇬🇧 trigger word "handoff"
    AGENTS.md                protocol + self-maintenance rules
    HANDOFF.md               the handoff sheet
    .github/
      copilot-instructions.md
      prompts/handoff.prompt.md   →  /handoff in VS Code
hooks/
  handoff-trigger.sh         trigger-word context injection
  handoff-snapshot.sh        session-end git snapshot
  README.md                  setup for Kimi Code & Claude Code

⚠️ Notes

• Remote agents (Copilot coding agent on GitHub) only see committed and pushed files — commit your handoff updates.
• Hook scripts are fail-open: any error exits silently and never blocks work.

---

Stop re-explaining your project to machines.

MIT © LICENSE · If this saved your context, a ⭐ saves ours.