claude-context-auto-handoff 1.0.1 → 1.0.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "context-handoff",
+  "description": "Claude Code plugin for automatic session context handoff across compactions and stops.",
+  "owner": {
+    "name": "Ethualo",
+    "email": "lkh0926ym@naver.com"
+  },
+  "plugins": [
+    {
+      "name": "claude-context-handoff",
+      "displayName": "Context Auto-Handoff",
+      "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
+      "source": {
+        "source": "npm",
+        "package": "claude-context-auto-handoff"
+      },
+      "homepage": "https://github.com/Ethualo/claude-context-auto-handoff",
+      "repository": "https://github.com/Ethualo/claude-context-auto-handoff",
+      "license": "MIT",
+      "author": {
+        "name": "Ethualo",
+        "email": "lkh0926ym@naver.com"
+      },
+      "keywords": ["context", "handoff", "session", "memory", "compaction", "claude-code"],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -6,9 +6,11 @@
     "name": "Ethualo",
     "email": "lkh0926ym@naver.com"
   },
-  "engines": {
-    "claude": "^1.0.0"
-  },
+  "homepage": "https://github.com/Ethualo/claude-context-auto-handoff",
+  "repository": "https://github.com/Ethualo/claude-context-auto-handoff",
+  "license": "MIT",
+  "keywords": ["context", "handoff", "session", "memory", "compaction", "claude-code"],
+  "category": "productivity",
   "mcpServers": {
     "context-handoff-manager": {
       "command": "node",

package/README.ko.md

@@ -6,7 +6,13 @@
 
 ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
-![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%89%A51.0.0-orange)
+
+---
+
+## 필수 요구사항
+
+- **Node.js 18+** — `node` 명령어가 `PATH`에 있어야 함
+- **Claude Code** 또는 **Codex** — 플러그인 및 훅 실행에 Claude Code CLI 또는 Codex CLI 필요
 
 ---
 

package/README.md

@@ -6,7 +6,13 @@ Claude Code plugin that automatically saves session context and generates token-
 
 ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
-![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%89%A51.0.0-orange)
+
+---
+
+## Requirements
+
+- **Node.js 18+** — must be on `PATH` as `node`
+- **Claude Code** or **Codex** — plugin and hooks require Claude Code CLI or Codex CLI
 
 ---
 

package/build/index.js

@@ -9,23 +9,23 @@ const server = new McpServer({
     version: '1.0.0'
 });
 server.tool('generate_handoff_manifest', {
-    summary: z.string().optional().describe('Detailed session recap — omit if other fields cover it'),
-    nextSteps: z.array(z.string()).describe('Tasks to continue immediately in the next session'),
-    taskDescription: z.string().optional().describe('High-level goal + core intent (why this matters). Use telegraphese — drop articles/pronouns.'),
-    currentStatus: z.string().optional().describe('What is done vs what remains. State why, not just what.'),
-    keyDecisions: z.array(z.string()).optional().describe('Architecture choices and why — prevents post-compaction amnesia. Format: "Decision: X — Reason: Y"'),
-    failedApproaches: z.array(z.string()).optional().describe('Already-failed attempts. Format each: "Approach: X → Result: Y → Lesson: Z". Prevents repeating mistakes.'),
-    blockers: z.string().optional().describe('Unresolved errors or blockers'),
+    summary: z.string().optional().describe('Detailed session recap in English — omit if other fields cover it'),
+    nextSteps: z.array(z.string()).describe('Tasks to continue immediately in the next session. Write in English.'),
+    taskDescription: z.string().optional().describe('High-level goal + core intent (why this matters). Use telegraphese — drop articles/pronouns. Write in English.'),
+    currentStatus: z.string().optional().describe('What is done vs what remains. State why, not just what. Write in English.'),
+    keyDecisions: z.array(z.string()).optional().describe('Architecture choices and why — prevents post-compaction amnesia. Format: "Decision: X — Reason: Y". Write in English.'),
+    failedApproaches: z.array(z.string()).optional().describe('Already-failed attempts. Format each: "Approach: X → Result: Y → Lesson: Z". Prevents repeating mistakes. Write in English.'),
+    blockers: z.string().optional().describe('Unresolved errors or blockers. Write in English.'),
     modifiedFiles: z.array(z.string()).optional().describe('Changed files with delta notes. Format: "path/to/file: what changed" — NO code snippets, path+delta only.'),
-    implicitRules: z.array(z.string()).optional().describe('Tech stack, naming conventions, env vars, implicit project rules — anything not derivable from reading code')
-}, async ({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules }) => {
+    implicitRules: z.array(z.string()).optional().describe('Tech stack, naming conventions, env vars, implicit project rules — anything not derivable from reading code. Write in English.'),
+    workingDirectory: z.string().optional().describe('Absolute path to the project root where handoff.md should be written. Required on Windows where process.cwd() may return System32.')
+}, async ({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, workingDirectory }) => {
     try {
-        const claudeDir = path.join(process.cwd(), '.claude');
+        const projectRoot = workingDirectory || process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+        const claudeDir = path.join(projectRoot, '.claude');
         const handoffsDir = path.join(claudeDir, 'handoffs');
-        if (!fs.existsSync(claudeDir))
-            fs.mkdirSync(claudeDir, { recursive: true });
-        if (!fs.existsSync(handoffsDir))
-            fs.mkdirSync(handoffsDir, { recursive: true });
+        fs.mkdirSync(claudeDir, { recursive: true });
+        fs.mkdirSync(handoffsDir, { recursive: true });
         const now = new Date();
         const displayTime = now.toLocaleString();
         const timestamp = now.toISOString().replace(/[:.]/g, '-');

package/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "CRITICAL: Context compaction imminent. Call 'generate_handoff_manifest' NOW before compaction. Fill all fields: summary (full session recap), taskDescription (goal), currentStatus (done vs remaining), keyDecisions (architecture choices + why), failedApproaches (already-failed — do NOT retry), nextSteps (next session tasks), blockers (unresolved errors). Do NOT allow compaction without calling this tool."
+            "prompt": "CRITICAL: Context compaction imminent. Call 'generate_handoff_manifest' NOW before compaction. Fill all fields: summary (full session recap), taskDescription (goal), currentStatus (done vs remaining), keyDecisions (architecture choices + why), failedApproaches (already-failed — do NOT retry), nextSteps (next session tasks), blockers (unresolved errors). Write ALL field values in English. Do NOT allow compaction without calling this tool."
           }
         ]
       }
@@ -15,7 +15,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If a work unit just completed (feature done, tests passed, commit made), call 'generate_handoff_manifest'. Fill taskDescription, keyDecisions, and failedApproaches so the next session has full context."
+            "prompt": "If a work unit just completed (feature done, tests passed, commit made), call 'generate_handoff_manifest'. Fill taskDescription, keyDecisions, and failedApproaches so the next session has full context. Write ALL field values in English."
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-context-auto-handoff",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A Claude Code plugin to automate session handoffs before context compaction.",
   "type": "module",
   "main": "build/index.js",
@@ -12,6 +12,7 @@
     "build",
     ".claude-plugin",
     "hooks",
+    "skills",
     "templates",
     "scripts",
     "README.md",
@@ -33,4 +34,4 @@
     "@types/node": "^20.11.0",
     "typescript": "^5.3.3"
   }
-}
+}

package/scripts/setup.ps1

@@ -1,4 +1,4 @@
-# context-handoff-mcp-server — one-line setup for Windows (PowerShell)
+# context-handoff-mcp-server -- one-line setup for Windows (PowerShell)
 # Usage: irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 | iex
 
 $ErrorActionPreference = "Stop"
@@ -11,25 +11,25 @@ Write-Host "[Handoff Setup] Installing $PluginName..."
 # 1. npm global install (builds TypeScript)
 npm install -g claude-context-auto-handoff
 
-# 2. hooks.json 등록 (기존 파일이 있으면 경고만)
+# 2. Register hooks.json (warn if already exists)
 $NpmRoot = (npm root -g).Trim()
 $HooksSrc = Join-Path $NpmRoot "claude-context-auto-handoff\hooks\hooks.json"
 
 if (Test-Path $HooksTarget) {
-  Write-Host "[Handoff Setup] WARNING: $HooksTarget 이미 존재합니다."
-  Write-Host "  수동으로 $HooksSrc 내용을 병합하세요."
+  Write-Host "[Handoff Setup] WARNING: $HooksTarget already exists."
+  Write-Host "  Manually merge contents from: $HooksSrc"
 } else {
   $HooksDir = Split-Path $HooksTarget
   if (-not (Test-Path $HooksDir)) { New-Item -ItemType Directory -Force $HooksDir | Out-Null }
   Copy-Item $HooksSrc $HooksTarget
-  Write-Host "[Handoff Setup] hooks.json 등록 완료: $HooksTarget"
+  Write-Host "[Handoff Setup] hooks.json registered: $HooksTarget"
 }
 
 Write-Host ""
-Write-Host "[Handoff Setup] 완료!"
+Write-Host "[Handoff Setup] Done!"
 Write-Host ""
-Write-Host "  사용법:"
-Write-Host "    /handoff  — 현재 세션 저장"
-Write-Host "    /resume   — 이전 세션 복원"
+Write-Host "  Usage:"
+Write-Host "    /handoff  -- save current session"
+Write-Host "    /resume   -- restore previous session"
 Write-Host ""
-Write-Host "  SessionStart 훅이 세션 시작 시 자동으로 이전 컨텍스트를 복원합니다."
+Write-Host "  SessionStart hook auto-restores previous context on session open."

package/scripts/setup.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# context-handoff-mcp-server — one-line setup for Linux/macOS
+# context-handoff-mcp-server -- one-line setup for Linux/macOS
 # Usage: curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
 
 set -e
@@ -12,23 +12,23 @@ echo "[Handoff Setup] Installing $PLUGIN_NAME..."
 # 1. npm global install (builds TypeScript)
 npm install -g claude-context-auto-handoff
 
-# 2. hooks.json 등록 (기존 파일이 있으면 경고만)
+# 2. Register hooks.json (warn if already exists)
 HOOKS_SRC="$(npm root -g)/claude-context-auto-handoff/hooks/hooks.json"
 
 if [ -f "$HOOKS_TARGET" ]; then
-  echo "[Handoff Setup] WARNING: $HOOKS_TARGET 이미 존재합니다."
-  echo "  수동으로 $HOOKS_SRC 내용을 병합하세요."
+  echo "[Handoff Setup] WARNING: $HOOKS_TARGET already exists."
+  echo "  Manually merge contents from: $HOOKS_SRC"
 else
   mkdir -p "$(dirname "$HOOKS_TARGET")"
   cp "$HOOKS_SRC" "$HOOKS_TARGET"
-  echo "[Handoff Setup] hooks.json 등록 완료: $HOOKS_TARGET"
+  echo "[Handoff Setup] hooks.json registered: $HOOKS_TARGET"
 fi
 
 echo ""
-echo "[Handoff Setup] 완료!"
+echo "[Handoff Setup] Done!"
 echo ""
-echo "  사용법:"
-echo "    /handoff  — 현재 세션 저장"
-echo "    /resume   — 이전 세션 복원"
+echo "  Usage:"
+echo "    /handoff  -- save current session"
+echo "    /resume   -- restore previous session"
 echo ""
-echo "  SessionStart 훅이 세션 시작 시 자동으로 이전 컨텍스트를 복원합니다."
+echo "  SessionStart hook auto-restores previous context on session open."

package/skills/handoff/SKILL.md

@@ -0,0 +1,37 @@
+---
+description: Save current session context to handoff file. Use when user runs /handoff or asks to save session state before ending.
+---
+
+Save session context to `.claude/handoff.md` and timestamped archive to `.claude/handoffs/`.
+
+## Content Generation Rules (STRICT)
+
+Write all field values using telegraphese — drop articles, pronouns, polite words. Maximize density.
+
+- **NO code snippets** in any field. Reference file paths + line-level delta notes only.
+- **WHY over WHAT**: Every decision/status must state the reason, not just the action.
+- **failedApproaches**: Format each entry as `"Approach: X → Result: Y → Lesson: Z"`. This prevents the next session from repeating mistakes.
+- **taskDescription**: Include both Goal and Core Intent (why this matters to the project).
+- **implicitRules**: Capture tech stack, naming conventions, env vars — anything not derivable from reading the code.
+
+## Steps
+
+1. Gather from current session:
+   - taskDescription: final goal + core intent (why)
+   - summary: terse session recap (telegraphese)
+   - currentStatus: done vs remaining
+   - keyDecisions: architecture choices + why (prevents post-compaction amnesia)
+   - failedApproaches: already-failed attempts in `Approach→Result→Lesson` format
+   - blockers: unresolved errors
+   - modifiedFiles: changed files with delta notes (no code, path + what changed)
+   - implicitRules: stack, conventions, env vars
+
+2. Call `generate_handoff_manifest`:
+   - `summary`, `nextSteps` — required
+   - `taskDescription`, `currentStatus`, `keyDecisions`, `failedApproaches`, `modifiedFiles`, `implicitRules` — recommended
+   - `blockers` — optional
+
+3. Confirm to user:
+   - Latest: `.claude/handoff.md`
+   - Archive: `.claude/handoffs/handoff-{timestamp}.md`
+   - Next session: run `/resume` or SessionStart hook auto-restores

package/skills/resume/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Restore previous session context from handoff file. Use when user runs /resume or asks to continue from last session.
+---
+
+Reads `.claude/handoff.md`. Falls back to latest file in `.claude/handoffs/`.
+
+## Steps
+
+1. Read `.claude/handoff.md`
+2. If missing, find latest `handoff-*.md` in `.claude/handoffs/`
+3. If neither found: tell user "No handoff file. Run /handoff first."
+4. If found:
+   - Parse: Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps
+   - Brief user in their language
+   - Never retry Failed Approaches
+   - Start from first Next Step immediately