claude-context-auto-handoff

English | 한국어

Claude Code plugin that automatically saves session context and generates token-efficient handoff manifests before Claude compacts or stops.

Requirements

• Node.js 18+ — must be on PATH as node
• Claude Code or Codex — plugin and hooks require Claude Code CLI or Codex CLI

Overview

Claude's context window eventually fills and compacts — losing design decisions, active blockers, and next steps mid-session. This plugin hooks into PreCompact and Stop events to trigger an AI-authored handoff document before that happens, so the next session picks up exactly where this one left off.

Handoff content is written in telegraphese (no articles, no filler, no code snippets) and structured to maximize token efficiency while preserving all decision context the next session needs.

Components

Tools

• generate_handoff_manifest — Writes a structured .claude/handoff.md to the current project directory. Also archives to .claude/handoffs/handoff-{timestamp}.md.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | summary | string | ✅ | Terse session recap (telegraphese) | | nextSteps | string[] | ✅ | Ordered todo list for the next session | | taskDescription | string | ✗ | High-level goal + core intent (why this matters) | | currentStatus | string | ✗ | What is done vs what remains — state why, not just what | | keyDecisions | string[] | ✗ | Architecture choices and reasons. Format: "Decision: X — Reason: Y" | | failedApproaches | string[] | ✗ | Already-failed attempts. Format: "Approach: X → Result: Y → Lesson: Z" | | modifiedFiles | string[] | ✗ | Changed files with delta notes. Format: "path/to/file: what changed" — no code | | implicitRules | string[] | ✗ | Tech stack, naming conventions, env vars — anything not derivable from reading code | | blockers | string | ✗ | Unresolved errors or open questions |

Skills

| Command | Behavior | |---------|----------| | /handoff-save | Gather session context and call generate_handoff_manifest | | /handoff-resume | Read .claude/handoff.md and restore context in a new session |

Hooks

Claude Code hooks are built-in. Codex hooks require copying templates/.codex to your project root (see Codex installation).

| Event | Behavior | |-------|----------| | PreCompact | Prompts the model to call generate_handoff_manifest before context compression | | Stop | Warns if handoff is stale or missing after each response | | SessionStart | Auto-restores context from .claude/handoff.md if it exists |

Quick Start

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 | iex

npm (cross-platform)

npm install -g claude-context-auto-handoff
claude-context-handoff-setup

Installation

As a Claude Code plugin

claude plugin install claude-context-auto-handoff

As an npm package

npm install -g claude-context-auto-handoff
claude-context-handoff-setup  # hooks.json 자동 배치

Manual MCP configuration (Claude Code)

Add to your Claude Code settings.json:

{
  "mcpServers": {
    "context-handoff-manager": {
      "command": "node",
      "args": ["/path/to/build/index.js"]
    }
  }
}

Codex

Add to ~/.codex/config.toml (global MCP config):

[mcp_servers.context-handoff]
command = "node"
args = ["/path/to/build/index.js"]

Then copy the hook templates to your project root:

cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex

This enables the same SessionStart, PreCompact, and Stop hooks as Claude Code.

Usage

Claude Code

All three hooks fire automatically — SessionStart restores context on session open, PreCompact saves before compression, Stop warns if handoff is stale. Generated manifests are saved to .claude/handoff.md.

Manual checkpoint:

/handoff-save

Manual resume (if auto-restore didn't trigger):

/handoff-resume

Codex

Same three hooks fire automatically via .codex/hooks.json. No slash commands — hooks handle everything.

| Event | Behavior | |-------|----------| | SessionStart | Reads .claude/handoff.md and injects content as context | | PreCompact | Prompts Codex to call generate_handoff_manifest before compression | | Stop | Warns if handoff is stale (>5 min) or missing |

Output format

# Session Handoff Snapshot
> **Generated:** 6/22/2026, 3:30:00 PM

## 🎯 High-Level Objective
* **Goal:** Build Next.js 15 app syncing Supabase + Notion stock data in real-time
* **Core Intent:** Minimize client re-fetches via Zustand store — cost control

## 📌 Current State & Next Steps
* **Status:** Task 3 (Zustand store) complete
* **Blocker:** Notion API rate limit (3 req/s) — buffer layer needed
* **Next Action:** Implement Supabase Edge Functions debounce queue

## 🛠️ Modified Files Delta
* src/store/stockStore.ts: Zustand store skeleton + syncStatus state
* src/app/api/notion/sync/route.ts: POST handler written, Supabase not wired yet

## 🚫 Failed Approaches (DO NOT RETRY)
* Approach: Call Notion API directly from Server Actions → Result: Rate limit hit on re-render → Lesson: Queue middleware mandatory
* Approach: useEffect polling → Result: Supabase read usage spike → Lesson: Abandoned

## 🔑 Crucial Context & Implicit Rules
* Stack: Next.js 15 (App Router), Supabase v2, Zustand v5
* Naming: API endpoints always route.ts, PascalCase store names
* Env: NEXT_PUBLIC_SUPABASE_ANON_KEY active

---
*Run `/handoff-resume` in the next session to restore this context.*

License

MIT