claude-context-auto-handoff 1.0.7 → 1.0.8

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "claude-context-handoff",
-      "version": "1.0.7",
+      "version": "1.0.8",
       "displayName": "Context Auto-Handoff",
       "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
       "source": {

package/.claude-plugin/plugin.json

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

package/README.ko.md

@@ -71,17 +71,22 @@ Claude Code 훅은 기본 내장. Codex 훅은 `templates/.codex`를 프로젝
 **Linux / macOS**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
+# Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md):
+curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash -s -- --codex
 ```
 
 **Windows (PowerShell)**
 ```powershell
-irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 | iex
+irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 -OutFile setup.ps1
+.\setup.ps1          # Claude Code만
+.\setup.ps1 -Codex   # Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md)
 ```
 
 **npm (크로스플랫폼)**
 ```bash
 npm install -g claude-context-auto-handoff
-claude-context-handoff-setup
+claude-context-handoff-setup           # Claude Code만
+claude-context-handoff-setup --codex   # Codex도 함께 설정
 ```
 
 ---
@@ -98,7 +103,7 @@ claude plugin install claude-context-auto-handoff
 
 ```bash
 npm install -g claude-context-auto-handoff
-claude-context-handoff-setup  # hooks.json 자동 배치
+claude-context-handoff-setup  # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
 ```
 
 ### MCP 수동 설정 (Claude Code)
@@ -126,13 +131,14 @@ command = "node"
 args = ["/path/to/build/index.js"]
 ```
 
-그런 다음 훅 템플릿을 프로젝트 루트에 복사:
+그런 다음 훅 템플릿과 지시문을 프로젝트 루트에 복사:
 
 ```bash
 cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
+cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
 ```
 
-Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화됩니다.
+Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화되고, 핸드오프 초안 작성+저장을 메인 스레드 밖에서 처리하는 `handoff-drafter` 서브에이전트(`.codex/agents/handoff-drafter.toml`)도 함께 활성화됩니다.
 
 ---
 
@@ -164,7 +170,7 @@ Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화
 | 이벤트 | 동작 |
 |--------|------|
 | `SessionStart` | `.claude/handoff.md`를 읽어 컨텍스트로 주입 |
-| `PreCompact` | 압축 전 handoff-save 스킬(Haiku 서브에이전트) 호출 지시 |
+| `PreCompact` | 압축 전 `handoff-drafter` 서브에이전트에 위임 지시 |
 | `Stop` | 핸드오프가 오래됐거나 없으면 경고 |
 
 ### 출력 형식

package/README.md

@@ -71,17 +71,22 @@ Claude Code hooks are built-in. Codex hooks require copying `templates/.codex` t
 **Linux / macOS**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
+# Also set up Codex (hooks + handoff-drafter subagent + AGENTS.md):
+curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash -s -- --codex
 ```
 
 **Windows (PowerShell)**
 ```powershell
-irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 | iex
+irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 -OutFile setup.ps1
+.\setup.ps1          # Claude Code only
+.\setup.ps1 -Codex   # also set up Codex (hooks + handoff-drafter subagent + AGENTS.md)
 ```
 
 **npm (cross-platform)**
 ```bash
 npm install -g claude-context-auto-handoff
-claude-context-handoff-setup
+claude-context-handoff-setup           # Claude Code only
+claude-context-handoff-setup --codex   # also set up Codex
 ```
 
 ---
@@ -98,7 +103,7 @@ claude plugin install claude-context-auto-handoff
 
 ```bash
 npm install -g claude-context-auto-handoff
-claude-context-handoff-setup  # hooks.json 자동 배치
+claude-context-handoff-setup  # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
 ```
 
 ### Manual MCP configuration (Claude Code)
@@ -126,13 +131,14 @@ command = "node"
 args = ["/path/to/build/index.js"]
 ```
 
-Then copy the hook templates to your project root:
+Then copy the hook templates and instructions to your project root:
 
 ```bash
 cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
+cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
 ```
 
-This enables the same `SessionStart`, `PreCompact`, and `Stop` hooks as Claude Code.
+This enables the same `SessionStart`, `PreCompact`, and `Stop` hooks as Claude Code, plus a `handoff-drafter` subagent (`.codex/agents/handoff-drafter.toml`) that drafts and saves the handoff so it doesn't run in your main thread.
 
 ---
 
@@ -164,7 +170,7 @@ Same three hooks fire automatically via `.codex/hooks.json`. No slash commands
 | Event | Behavior |
 |-------|----------|
 | `SessionStart` | Reads `.claude/handoff.md` and injects content as context |
-| `PreCompact` | Prompts Codex to invoke the handoff-save skill (Haiku subagent) before compression |
+| `PreCompact` | Prompts Codex to delegate to the `handoff-drafter` subagent before compression |
 | `Stop` | Warns if handoff is stale (>5 min) or missing |
 
 ### Output format

package/package.json

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

package/scripts/setup.js

@@ -4,9 +4,12 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const withCodex = process.argv.slice(2).includes('--codex');
 
 if (process.platform === 'win32') {
-  execSync(`powershell -ExecutionPolicy Bypass -File "${join(__dirname, 'setup.ps1')}"`, { stdio: 'inherit' });
+  const codexFlag = withCodex ? ' -Codex' : '';
+  execSync(`powershell -ExecutionPolicy Bypass -File "${join(__dirname, 'setup.ps1')}"${codexFlag}`, { stdio: 'inherit' });
 } else {
-  execSync(`bash "${join(__dirname, 'setup.sh')}"`, { stdio: 'inherit' });
+  const codexFlag = withCodex ? ' --codex' : '';
+  execSync(`bash "${join(__dirname, 'setup.sh')}"${codexFlag}`, { stdio: 'inherit' });
 }

package/scripts/setup.ps1

@@ -1,5 +1,10 @@
 # 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
+# Codex support: run the downloaded file with -Codex, e.g. .\setup.ps1 -Codex
+
+param(
+  [switch]$Codex
+)
 
 $ErrorActionPreference = "Stop"
 
@@ -11,9 +16,11 @@ Write-Host "[Handoff Setup] Installing $PluginName..."
 # 1. npm global install (builds TypeScript)
 npm install -g claude-context-auto-handoff
 
-# 2. Register hooks.json (warn if already exists)
 $NpmRoot = (npm root -g).Trim()
-$HooksSrc = Join-Path $NpmRoot "claude-context-auto-handoff\hooks\hooks.json"
+$PkgRoot = Join-Path $NpmRoot "claude-context-auto-handoff"
+
+# 2. Register hooks.json (warn if already exists)
+$HooksSrc = Join-Path $PkgRoot "hooks\hooks.json"
 
 if (Test-Path $HooksTarget) {
   Write-Host "[Handoff Setup] WARNING: $HooksTarget already exists."
@@ -25,6 +32,47 @@ if (Test-Path $HooksTarget) {
   Write-Host "[Handoff Setup] hooks.json registered: $HooksTarget"
 }
 
+if ($Codex) {
+  Write-Host ""
+  Write-Host "[Handoff Setup] Configuring Codex..."
+
+  # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
+  $CodexConfig = "$env:USERPROFILE\.codex\config.toml"
+  $ServerBin = Join-Path $PkgRoot "build\index.js"
+  $CodexConfigDir = Split-Path $CodexConfig
+  if (-not (Test-Path $CodexConfigDir)) { New-Item -ItemType Directory -Force $CodexConfigDir | Out-Null }
+  if (-not (Test-Path $CodexConfig)) { New-Item -ItemType File -Path $CodexConfig | Out-Null }
+
+  $existingConfig = Get-Content $CodexConfig -Raw -ErrorAction SilentlyContinue
+  if ($existingConfig -and $existingConfig.Contains("mcp_servers.context-handoff")) {
+    Write-Host "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CodexConfig — skipping."
+  } else {
+    $TomlBlock = @"
+
+[mcp_servers.context-handoff]
+command = "node"
+args = ["$($ServerBin.Replace('\','\\'))"]
+"@
+    Add-Content -Path $CodexConfig -Value $TomlBlock
+    Write-Host "[Handoff Setup] MCP server registered: $CodexConfig"
+  }
+
+  # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
+  if (Test-Path ".\.codex") {
+    Write-Host "[Handoff Setup] WARNING: .\.codex already exists — not overwritten. Reference: $PkgRoot\templates\.codex"
+  } else {
+    Copy-Item (Join-Path $PkgRoot "templates\.codex") ".\.codex" -Recurse
+    Write-Host "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: .\.codex"
+  }
+
+  if (Test-Path ".\AGENTS.md") {
+    Write-Host "[Handoff Setup] WARNING: .\AGENTS.md already exists — not overwritten. Reference: $PkgRoot\templates\AGENTS.md"
+  } else {
+    Copy-Item (Join-Path $PkgRoot "templates\AGENTS.md") ".\AGENTS.md"
+    Write-Host "[Handoff Setup] AGENTS.md copied: .\AGENTS.md"
+  }
+}
+
 Write-Host ""
 Write-Host "[Handoff Setup] Done!"
 Write-Host ""

package/scripts/setup.sh

@@ -1,19 +1,29 @@
 #!/usr/bin/env bash
 # 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
+# Codex support:  ... | bash -s -- --codex
 
 set -e
 
 PLUGIN_NAME="claude-context-handoff"
 HOOKS_TARGET="$HOME/.claude/hooks.json"
+WITH_CODEX=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --codex) WITH_CODEX=true ;;
+  esac
+done
 
 echo "[Handoff Setup] Installing $PLUGIN_NAME..."
 
 # 1. npm global install (builds TypeScript)
 npm install -g claude-context-auto-handoff
 
+PKG_ROOT="$(npm root -g)/claude-context-auto-handoff"
+
 # 2. Register hooks.json (warn if already exists)
-HOOKS_SRC="$(npm root -g)/claude-context-auto-handoff/hooks/hooks.json"
+HOOKS_SRC="$PKG_ROOT/hooks/hooks.json"
 
 if [ -f "$HOOKS_TARGET" ]; then
   echo "[Handoff Setup] WARNING: $HOOKS_TARGET already exists."
@@ -24,6 +34,44 @@ else
   echo "[Handoff Setup] hooks.json registered: $HOOKS_TARGET"
 fi
 
+if [ "$WITH_CODEX" = true ]; then
+  echo ""
+  echo "[Handoff Setup] Configuring Codex..."
+
+  # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
+  CODEX_CONFIG="$HOME/.codex/config.toml"
+  SERVER_BIN="$PKG_ROOT/build/index.js"
+  mkdir -p "$(dirname "$CODEX_CONFIG")"
+  touch "$CODEX_CONFIG"
+
+  if grep -q "mcp_servers.context-handoff" "$CODEX_CONFIG" 2>/dev/null; then
+    echo "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CODEX_CONFIG — skipping."
+  else
+    {
+      echo ""
+      echo "[mcp_servers.context-handoff]"
+      echo "command = \"node\""
+      echo "args = [\"$SERVER_BIN\"]"
+    } >> "$CODEX_CONFIG"
+    echo "[Handoff Setup] MCP server registered: $CODEX_CONFIG"
+  fi
+
+  # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
+  if [ -d "./.codex" ]; then
+    echo "[Handoff Setup] WARNING: ./.codex already exists — not overwritten. Reference: $PKG_ROOT/templates/.codex"
+  else
+    cp -r "$PKG_ROOT/templates/.codex" ./.codex
+    echo "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: ./.codex"
+  fi
+
+  if [ -f "./AGENTS.md" ]; then
+    echo "[Handoff Setup] WARNING: ./AGENTS.md already exists — not overwritten. Reference: $PKG_ROOT/templates/AGENTS.md"
+  else
+    cp "$PKG_ROOT/templates/AGENTS.md" ./AGENTS.md
+    echo "[Handoff Setup] AGENTS.md copied: ./AGENTS.md"
+  fi
+fi
+
 echo ""
 echo "[Handoff Setup] Done!"
 echo ""

package/templates/.codex/agents/handoff-drafter.toml

@@ -0,0 +1,17 @@
+name = "handoff-drafter"
+description = "Drafts and saves a session handoff via generate_handoff_manifest. Use before context compaction, or when a session with meaningful work is ending."
+developer_instructions = """
+Draft the handoff fields from the parent session's context, following the Content Generation Rules in AGENTS.md (telegraphese — drop articles/pronouns/filler; WHY over WHAT; no code snippets, path + delta notes only; failedApproaches as "Approach: X -> Result: Y -> Lesson: Z").
+
+Then call generate_handoff_manifest yourself with:
+  - summary, nextSteps (required)
+  - taskDescription, currentStatus, keyDecisions, failedApproaches, modifiedFiles, implicitRules (recommended)
+  - blockers (optional)
+  - workingDirectory: absolute path to the project root (passed to you by the caller) — always set this explicitly, never rely on the tool's cwd fallback.
+
+Report back only a short confirmation: the saved paths (.claude/handoff.md and the archive path). Do not return the drafted field content to the caller.
+"""
+
+# Optional: pin to a lighter/cheaper model to cut cost on this drafting task,
+# e.g. model = "gpt-5.3-codex-spark". Omitted here so it inherits the parent
+# session's model/sandbox settings by default.

package/templates/.codex/hooks.json

@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"console.log('CRITICAL: Context is about to be compressed. You MUST invoke the handoff-save skill NOW (it delegates drafting + calling generate_handoff_manifest to a cheap subagent — do not draft the fields or call the tool yourself) with a complete session summary before this happens. Include: summary, nextSteps, taskDescription, currentStatus, keyDecisions, failedApproaches, modifiedFiles, implicitRules. Do not skip this step.')\"",
+            "command": "node -e \"console.log('CRITICAL: Context is about to be compressed. Delegate to the handoff-drafter subagent NOW per AGENTS.md (pass it this project absolute root path) before this happens. Do not skip this step.')\"",
             "timeout": 5,
             "statusMessage": "Saving handoff before compaction"
           }
@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const fs=require('fs'),path=require('path');const f=path.join(process.cwd(),'.claude','handoff.md');if(!fs.existsSync(f)){console.log('No handoff file found. If this session had meaningful work, invoke the handoff-save skill before ending (it delegates to a cheap subagent).')}else{const age=(Date.now()-fs.statSync(f).mtimeMs)/1000;if(age>300){console.log('HANDOFF STALE (last saved '+Math.round(age/60)+' min ago). Invoke the handoff-save skill to update session context.')}}\"",
+            "command": "node -e \"const fs=require('fs'),path=require('path');const f=path.join(process.cwd(),'.claude','handoff.md');if(!fs.existsSync(f)){console.log('No handoff file found. If this session had meaningful work, delegate to the handoff-drafter subagent per AGENTS.md before ending.')}else{const age=(Date.now()-fs.statSync(f).mtimeMs)/1000;if(age>300){console.log('HANDOFF STALE (last saved '+Math.round(age/60)+' min ago). Delegate to the handoff-drafter subagent per AGENTS.md to update session context.')}}\"",
             "timeout": 5,
             "statusMessage": "Checking handoff status"
           }

package/templates/AGENTS.md

@@ -10,7 +10,9 @@ If the file does not exist, proceed normally.
 
 ## Session End / Before Context Grows Large
 
-Before ending the session or when the conversation is getting long, call `generate_handoff_manifest` with the following fields:
+Before ending the session or when the conversation is getting long, delegate to the `handoff-drafter` subagent (`.codex/agents/handoff-drafter.toml`) rather than drafting the fields or calling the tool yourself — it can run on a lighter model and keeps the drafted content out of this thread. Pass it the project's absolute root path so it can set `workingDirectory` correctly (it runs with its own cwd).
+
+If the `handoff-drafter` subagent is unavailable, fall back to calling `generate_handoff_manifest` directly with these fields:
 
 | Field | Required | Format |
 |-------|----------|--------|
@@ -23,6 +25,7 @@ Before ending the session or when the conversation is getting long, call `genera
 | `modifiedFiles` | recommended | `"path/to/file: what changed"` — NO code snippets |
 | `implicitRules` | recommended | Tech stack, naming conventions, env vars |
 | `blockers` | optional | Unresolved errors or open questions |
+| `workingDirectory` | recommended | Absolute path to this project's root. Pass it explicitly — do not rely on the tool's cwd fallback. |
 
 Output is saved to `.claude/handoff.md` (latest) and `.claude/handoffs/handoff-{timestamp}.md` (archive).