claude-context-auto-handoff 1.0.4 → 1.0.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-context-handoff",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
   "author": {
     "name": "Ethualo",

package/README.ko.md

@@ -46,8 +46,8 @@ Claude의 컨텍스트 창이 가득 차면 대화가 자동으로 압축됩니
 
 | 명령어 | 동작 |
 |--------|------|
-| `/handoff` | 세션 컨텍스트 수집 후 `generate_handoff_manifest` 호출 |
-| `/resume` | `.claude/handoff.md` 읽어 새 세션에서 컨텍스트 복원 |
+| `/handoff-save` | 세션 컨텍스트 수집 후 `generate_handoff_manifest` 호출 |
+| `/handoff-resume` | `.claude/handoff.md` 읽어 새 세션에서 컨텍스트 복원 |
 
 ### 훅 (Hooks)
 
@@ -93,7 +93,7 @@ claude plugin install claude-context-auto-handoff
 
 ```bash
 npm install -g claude-context-auto-handoff
-npm run setup  # hooks.json 자동 배치
+claude-context-handoff-setup  # hooks.json 자동 배치
 ```
 
 ### MCP 수동 설정 (Claude Code)
@@ -139,12 +139,12 @@ Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화
 
 **수동 체크포인트:**
 ```
-/handoff
+/handoff-save
 ```
 
 **수동 복원 (자동 복원이 실행되지 않은 경우):**
 ```
-/resume
+/handoff-resume
 ```
 
 ### Codex
@@ -186,7 +186,7 @@ Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화
 * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY 사용 중
 
 ---
-*다음 세션 시작 시 자동으로 컨텍스트가 복원됩니다. 수동 복원: `/resume`*
+*다음 세션 시작 시 자동으로 컨텍스트가 복원됩니다. 수동 복원: `/handoff-resume`*
 ```
 
 ---

package/README.md

@@ -46,8 +46,8 @@ Handoff content is written in **telegraphese** (no articles, no filler, no code
 
 | Command | Behavior |
 |---------|----------|
-| `/handoff` | Gather session context and call `generate_handoff_manifest` |
-| `/resume` | Read `.claude/handoff.md` and restore context in a new session |
+| `/handoff-save` | Gather session context and call `generate_handoff_manifest` |
+| `/handoff-resume` | Read `.claude/handoff.md` and restore context in a new session |
 
 ### Hooks
 
@@ -93,7 +93,7 @@ claude plugin install claude-context-auto-handoff
 
 ```bash
 npm install -g claude-context-auto-handoff
-npm run setup  # hooks.json 자동 배치
+claude-context-handoff-setup  # hooks.json 자동 배치
 ```
 
 ### Manual MCP configuration (Claude Code)
@@ -139,12 +139,12 @@ All three hooks fire automatically — `SessionStart` restores context on sessio
 
 **Manual checkpoint:**
 ```
-/handoff
+/handoff-save
 ```
 
 **Manual resume (if auto-restore didn't trigger):**
 ```
-/resume
+/handoff-resume
 ```
 
 ### Codex
@@ -186,7 +186,7 @@ Same three hooks fire automatically via `.codex/hooks.json`. No slash commands
 * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY active
 
 ---
-*Run `/resume` in the next session to restore this context.*
+*Run `/handoff-resume` in the next session to restore this context.*
 ```
 
 ---

package/build/index.js

@@ -29,11 +29,14 @@ server.tool('generate_handoff_manifest', {
         const now = new Date();
         const displayTime = now.toLocaleString();
         const timestamp = now.toISOString().replace(/[:.]/g, '-');
-        const content = buildMarkdown({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, displayTime });
+        const content = buildMarkdown({ summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, displayTime, project: path.basename(projectRoot), isoDate: now.toISOString() });
         const mainPath = path.join(claudeDir, 'handoff.md');
         fs.writeFileSync(mainPath, content, 'utf-8');
-        const archivePath = path.join(handoffsDir, `handoff-${timestamp}.md`);
+        const dateDir = path.join(handoffsDir, now.toISOString().slice(0, 10));
+        fs.mkdirSync(dateDir, { recursive: true });
+        const archivePath = path.join(dateDir, `handoff-${timestamp}.md`);
         fs.writeFileSync(archivePath, content, 'utf-8');
+        pruneHandoffs(handoffsDir, 50);
         return {
             content: [{
                     type: 'text',
@@ -48,9 +51,36 @@ server.tool('generate_handoff_manifest', {
         };
     }
 });
+function pruneHandoffs(handoffsDir, keep) {
+    const dateDirs = fs.readdirSync(handoffsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    const files = dateDirs.flatMap(d => {
+        const dirPath = path.join(handoffsDir, d.name);
+        return fs.readdirSync(dirPath).map(name => ({ path: path.join(dirPath, name), name }));
+    });
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    const excess = files.length - keep;
+    if (excess > 0) {
+        files.slice(0, excess).forEach(f => fs.unlinkSync(f.path));
+    }
+    for (const d of dateDirs) {
+        const dirPath = path.join(handoffsDir, d.name);
+        if (fs.readdirSync(dirPath).length === 0)
+            fs.rmdirSync(dirPath);
+    }
+}
 function buildMarkdown(params) {
-    const { summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, displayTime } = params;
+    const { summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, blockers, modifiedFiles, implicitRules, displayTime, project, isoDate } = params;
+    const frontmatter = [
+        `---`,
+        `date: ${isoDate}`,
+        `project: ${project}`,
+        `next_steps_count: ${nextSteps.length}`,
+        `has_blockers: ${Boolean(blockers)}`,
+        `---`,
+        ``
+    ].join('\n');
     const sections = [
+        frontmatter,
         `# Session Handoff Snapshot`,
         `> **Generated:** ${displayTime}`,
         ``
@@ -89,7 +119,7 @@ function buildMarkdown(params) {
     if (summary) {
         sections.push(`## Summary\n${summary}\n`);
     }
-    sections.push(`---\n*Context is auto-restored on session start. Manual restore: \`/resume\`*`);
+    sections.push(`---\n*Context is auto-restored on session start. Manual restore: \`/handoff-resume\`*`);
     return sections.join('\n');
 }
 async function main() {

package/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Evaluate whether context compaction should proceed.\n\nContext: $ARGUMENTS\n\nRules:\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If the session has minimal context (just started, no significant work done), respond: {\"ok\": true}\n- If there is meaningful session context worth preserving (decisions, progress, failures) and 'generate_handoff_manifest' was NOT called yet, respond: {\"ok\": false, \"reason\": \"Context compaction imminent. Call 'generate_handoff_manifest' to preserve session state. 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.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
+            "prompt": "Evaluate whether context compaction should proceed.\n\nContext: $ARGUMENTS\n\nRules (check in order, use the first that matches):\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If the session has minimal context (just started, no significant work done), respond: {\"ok\": true}\n- If a 'PreCompact hook feedback' message with this same reason already appears earlier in the context (i.e. Claude was already asked to call generate_handoff_manifest before compaction and has not done so after a real opportunity), respond: {\"ok\": true} — do NOT block compaction again; blocking compaction indefinitely risks hitting the hard context limit, which is worse than compacting without a fresh handoff.\n- If there is meaningful session context worth preserving (decisions, progress, failures) and 'generate_handoff_manifest' was NOT called yet, respond: {\"ok\": false, \"reason\": \"Context compaction imminent. Call 'generate_handoff_manifest' to preserve session state. 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.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
             "timeout": 15
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Evaluate whether Claude should stop working.\n\nContext: $ARGUMENTS\n\nRules:\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If no meaningful work was done (e.g., simple Q&A, clarification, no code changes), respond: {\"ok\": true}\n- If meaningful work was completed (code changes, feature implementation, bug fix, tests) but 'generate_handoff_manifest' was NOT called yet, respond: {\"ok\": false, \"reason\": \"A work unit was completed. Call 'generate_handoff_manifest' with taskDescription, keyDecisions, failedApproaches, and nextSteps so the next session has full context. Write ALL field values in English.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
+            "prompt": "Evaluate whether Claude should stop working.\n\nContext: $ARGUMENTS\n\nRules (check in order, use the first that matches):\n- If 'generate_handoff_manifest' has already been called in this session, respond: {\"ok\": true}\n- If no meaningful work was done (e.g., simple Q&A, clarification, no code changes), respond: {\"ok\": true}\n- If Claude is only waiting on background/async work (subagents still running, a build/test in progress, an external process not yet finished) and has nothing new to act on right now, respond: {\"ok\": true} — do not force a handoff mid-wait; this hook will fire again once that work actually finishes.\n- If a 'Stop hook feedback' message with this same reason already appears earlier in the context (i.e. Claude was already asked to call generate_handoff_manifest for this work and has not done so after a real opportunity), respond: {\"ok\": true} — do not repeat the same block forever.\n- If the completed work is trivial (a single small edit, a one-line fix, a doc/comment tweak, a config nudge confined to one file), respond: {\"ok\": true} — too small to warrant a handoff.\n- Otherwise, BOTH conditions below must hold before blocking — if either is false, respond {\"ok\": true} and let the session continue normally without a handoff:\n  (a) Substantial work was completed: spans multiple files, or is a completed feature/bug fix/refactor with real design decisions behind it.\n  (b) The context window actually looks like it is filling up: judge this from what you can observe in the current session — many turns, many tool calls, large files read, long tool outputs, extensive exploration or back-and-forth. A short session with only a few turns/tool calls does NOT meet this bar even if the work itself was substantial — there is no hook-level API for exact token/context-window percentage, so this is a visible-session-size heuristic, not a precise measurement.\n- If (a) AND (b) both hold, 'generate_handoff_manifest' was NOT called yet, this is the first time asking, and no background work is pending, respond: {\"ok\": false, \"reason\": \"A substantial work unit was completed and this session's context looks like it is filling up. Call 'generate_handoff_manifest' with taskDescription, keyDecisions, failedApproaches, and nextSteps so the next session has full context. Write ALL field values in English.\"}\n\nIMPORTANT: Respond ONLY with a single JSON object. No markdown formatting, no explanation, no code blocks.",
             "timeout": 15
           }
         ]
@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "On session start: if .claude/handoff.md exists, read it and briefly brief the user (in their language) on Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps. If absent, stay silent.",
+            "prompt": "On session start: check if .claude/handoff.md exists.\n\nRules:\n- If it is missing, or exists but is empty/unparseable (e.g. no frontmatter, no recognizable sections), stay silent.\n- Otherwise, read it and briefly brief the user (in their language) on Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps.\n- Check the frontmatter `date` field. If it is more than 3 days before today, prepend a short staleness note to the brief (e.g. 'this handoff is N days old, may be outdated') so the user knows to double-check before trusting it.",
             "timeout": 10
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-context-auto-handoff",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A Claude Code plugin to automate session handoffs before context compaction.",
   "type": "module",
   "main": "build/index.js",

package/scripts/setup.ps1

@@ -29,7 +29,7 @@ Write-Host ""
 Write-Host "[Handoff Setup] Done!"
 Write-Host ""
 Write-Host "  Usage:"
-Write-Host "    /handoff  -- save current session"
-Write-Host "    /resume   -- restore previous session"
+Write-Host "    /handoff-save    -- save current session"
+Write-Host "    /handoff-resume  -- restore previous session"
 Write-Host ""
 Write-Host "  SessionStart hook auto-restores previous context on session open."

package/scripts/setup.sh

@@ -28,7 +28,7 @@ echo ""
 echo "[Handoff Setup] Done!"
 echo ""
 echo "  Usage:"
-echo "    /handoff  -- save current session"
-echo "    /resume   -- restore previous session"
+echo "    /handoff-save    -- save current session"
+echo "    /handoff-resume  -- restore previous session"
 echo ""
 echo "  SessionStart hook auto-restores previous context on session open."

package/skills/{resume → handoff-resume}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Restore previous session context from handoff file. Use when user runs /resume or asks to continue from last session.
+description: Restore previous session context from handoff file. Use when user runs /handoff-resume or asks to continue from last session.
 ---
 
 Reads `.claude/handoff.md`. Falls back to latest file in `.claude/handoffs/`.
@@ -8,7 +8,7 @@ Reads `.claude/handoff.md`. Falls back to latest file in `.claude/handoffs/`.
 
 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."
+3. If neither found: tell user "No handoff file. Run /handoff-save first."
 4. If found:
    - Parse: Task Description, Current Status, Key Decisions, Failed Approaches, Blockers, Next Steps
    - Brief user in their language

package/skills/{handoff → handoff-save}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Save current session context to handoff file. Use when user runs /handoff or asks to save session state before ending.
+description: Save current session context to handoff file. Use when user runs /handoff-save or asks to save session state before ending.
 ---
 
 Save session context to `.claude/handoff.md` and timestamped archive to `.claude/handoffs/`.
@@ -34,4 +34,4 @@ Write all field values using telegraphese — drop articles, pronouns, polite wo
 3. Confirm to user:
    - Latest: `.claude/handoff.md`
    - Archive: `.claude/handoffs/handoff-{timestamp}.md`
-   - Next session: run `/resume` or SessionStart hook auto-restores
+   - Next session: run `/handoff-resume` or SessionStart hook auto-restores