claude-context-auto-handoff 1.0.8 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/README.ko.md +212 -212
  4. package/README.md +212 -212
  5. package/package.json +1 -1
  6. package/scripts/setup.ps1 +83 -83
  7. package/scripts/setup.sh +82 -82
package/.claude-plugin/marketplace.json CHANGED
@@ -8,7 +8,7 @@
8
8
  "plugins": [
9
9
  {
10
10
  "name": "claude-context-handoff",
11
- "version": "1.0.8",
11
+ "version": "1.0.9",
12
12
  "displayName": "Context Auto-Handoff",
13
13
  "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
14
14
  "source": {
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-context-handoff",
3
- "version": "1.0.8",
3
+ "version": "1.0.9",
4
4
  "description": "Automatically saves session context and generates handoff manifests before Claude compacts or stops.",
5
5
  "author": {
6
6
  "name": "Ethualo",
package/README.ko.md CHANGED
@@ -1,212 +1,212 @@
1
- # claude-context-auto-handoff
2
-
3
- **[English](README.md)** | 한국어
4
-
5
- 컨텍스트 압축이나 세션 종료 직전, 다음 세션이 현재 맥락을 그대로 이어받도록 토큰 효율적인 핸드오프 문서를 자동으로 써 두는 Claude Code 플러그인.
6
-
7
- ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
8
- ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
9
-
10
- ---
11
-
12
- ## 필수 요구사항
13
-
14
- - **Node.js 18+** — `node` 명령어가 `PATH`에 있어야 함
15
- - **Claude Code** 또는 **Codex** — 플러그인 및 훅 실행에 Claude Code CLI 또는 Codex CLI 필요
16
-
17
- ---
18
-
19
- ## 개요
20
-
21
- Claude의 컨텍스트 창이 가득 차면 대화가 자동으로 압축됩니다. 이때 방금 내린 설계 결정, 해결 중이던 버그, 다음 할 일이 흐릿해집니다. 이 플러그인은 `PreCompact`와 `Stop` 이벤트를 감지해 압축 전에 AI가 직접 핸드오프 문서를 씁니다. 다음 세션은 그 파일 하나로 즉시 이어집니다.
22
-
23
- 핸드오프 내용은 **텔레그래피즘**(관사·군더더기·코드 스니펫 없음)으로 작성해 토큰은 아끼면서도 다음 세션에 필요한 결정 맥락은 그대로 남깁니다.
24
-
25
- 초안 작성(1회 저장당 3-6k 토큰 규모)은 Haiku 서브에이전트에 위임되며, 서브에이전트가 `generate_handoff_manifest` 호출까지 직접 수행합니다 — 초안이 메인 세션 모델 컨텍스트를 거치지 않습니다.
26
-
27
- ---
28
-
29
- ## 구성 요소
30
-
31
- ### 도구 (Tools)
32
-
33
- - **`generate_handoff_manifest`** — 현재 프로젝트의 `.claude/handoff.md`에 구조화된 핸드오프 문서를 저장합니다. `.claude/handoffs/{YYYY-MM-DD}/handoff-{timestamp}.md`에도 아카이브됩니다 (최근 50개 파일만 유지, 자동 정리). 동시에 `.claude/handoffs/index.md`에 한 줄 요약(날짜, 키워드, 헤드라인, 경로)을 upsert해 — 아카이브 파일을 전부 열지 않고도 grep 한 번으로 과거 세션을 찾을 수 있는 경량 인덱스를 유지합니다. 한 세션 안에서 여러 번 저장돼도(예: 긴 세션에서 `PreCompact`와 `Stop`이 둘 다 발동) 새 파일을 쌓지 않고 그 세션의 아카이브 파일·인덱스 줄을 그대로 갱신합니다 — MCP 서버 프로세스 하나당 세션ID 하나를 부여해 frontmatter `session:` 필드에 기록합니다.
34
-
35
- | 파라미터 | 타입 | 필수 | 설명 |
36
- |----------|------|------|------|
37
- | `nextSteps` | `string[]` | ✅ | 다음 세션에서 즉시 이어받을 할 일 목록 |
38
- | `summary` | `string` | ✗ | 간결한 세션 요약 (텔레그래피즘) — 다른 필드로 충분하면 생략 |
39
- | `taskDescription` | `string` | ✗ | 상위 목표 + 핵심 의도 (왜 중요한가) |
40
- | `currentStatus` | `string` | ✗ | 완료된 것 vs 남은 것 — 무엇이 아닌 왜를 명시 |
41
- | `keyDecisions` | `string[]` | ✗ | 아키텍처 결정과 이유. 형식: `"Decision: X — Reason: Y"` |
42
- | `failedApproaches` | `string[]` | ✗ | 이미 실패한 시도. 형식: `"Approach: X → Result: Y → Lesson: Z"` |
43
- | `modifiedFiles` | `string[]` | ✗ | 변경 파일과 델타 메모. 형식: `"경로/파일: 무엇을 변경"` — 코드 금지 |
44
- | `implicitRules` | `string[]` | ✗ | 기술 스택, 네이밍 컨벤션, 환경변수 — 코드에서 유추 불가한 규칙 |
45
- | `blockers` | `string` | ✗ | 미해결 에러 또는 막혀 있는 문제 |
46
- | `workingDirectory` | `string` | ✗ | handoff.md를 쓸 프로젝트 루트 절대 경로 — Windows에서 `process.cwd()`가 System32를 가리킬 때 필요 |
47
-
48
- ### 스킬 (Skills)
49
-
50
- | 명령어 | 동작 |
51
- |--------|------|
52
- | `/handoff-save` | Haiku 서브에이전트에 위임 — 세션 컨텍스트 초안 작성 + `generate_handoff_manifest` 호출까지 직접 수행 (3-6k 토큰 초안이 비싼 메인 모델을 거치지 않음) |
53
- | `/handoff-resume` | `.claude/handoff.md` 읽어 새 세션에서 컨텍스트 복원 |
54
- | `/handoff-search` | `.claude/handoffs/index.md`를 grep해 주제와 일치하는 과거 세션 검색 — DB·임베딩 없음 |
55
-
56
- ### 훅 (Hooks)
57
-
58
- Claude Code 훅은 기본 내장. Codex 훅은 `templates/.codex`를 프로젝트 루트에 복사해야 활성화됩니다 ([Codex 설치](#codex) 참조).
59
-
60
- | 이벤트 | 동작 |
61
- |--------|------|
62
- | `PreCompact` | 컨텍스트 압축 직전 `handoff-save` 스킬(Haiku 서브에이전트) 호출 지시 |
63
- | `Stop` | 핸드오프 파일이 오래됐거나 없으면 경고 |
64
- | `SessionStart` | 핸드오프 존재 시 짧은 힌트(경과 시간, 주제)만 노출 — 전체 내용은 키워드 매칭이나 `/handoff-resume`으로 로드 |
65
- | `UserPromptSubmit` | 프롬프트가 직전 핸드오프의 키워드와 일치하면 전체 컨텍스트 자동 주입 |
66
-
67
- ---
68
-
69
- ## 빠른 시작
70
-
71
- **Linux / macOS**
72
- ```bash
73
- curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
74
- # Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md):
75
- curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash -s -- --codex
76
- ```
77
-
78
- **Windows (PowerShell)**
79
- ```powershell
80
- irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 -OutFile setup.ps1
81
- .\setup.ps1 # Claude Code만
82
- .\setup.ps1 -Codex # Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md)
83
- ```
84
-
85
- **npm (크로스플랫폼)**
86
- ```bash
87
- npm install -g claude-context-auto-handoff
88
- claude-context-handoff-setup # Claude Code만
89
- claude-context-handoff-setup --codex # Codex도 함께 설정
90
- ```
91
-
92
- ---
93
-
94
- ## 설치
95
-
96
- ### Claude Code 플러그인으로 설치
97
-
98
- ```bash
99
- claude plugin install claude-context-auto-handoff
100
- ```
101
-
102
- ### npm 패키지로 설치
103
-
104
- ```bash
105
- npm install -g claude-context-auto-handoff
106
- claude-context-handoff-setup # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
107
- ```
108
-
109
- ### MCP 수동 설정 (Claude Code)
110
-
111
- Claude Code `settings.json`에 추가:
112
-
113
- ```json
114
- {
115
- "mcpServers": {
116
- "context-handoff-manager": {
117
- "command": "node",
118
- "args": ["/path/to/build/index.js"]
119
- }
120
- }
121
- }
122
- ```
123
-
124
- ### Codex
125
-
126
- `~/.codex/config.toml`에 추가 (전역 MCP 설정):
127
-
128
- ```toml
129
- [mcp_servers.context-handoff]
130
- command = "node"
131
- args = ["/path/to/build/index.js"]
132
- ```
133
-
134
- 그런 다음 훅 템플릿과 지시문을 프로젝트 루트에 복사:
135
-
136
- ```bash
137
- cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
138
- cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
139
- ```
140
-
141
- Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화되고, 핸드오프 초안 작성+저장을 메인 스레드 밖에서 처리하는 `handoff-drafter` 서브에이전트(`.codex/agents/handoff-drafter.toml`)도 함께 활성화됩니다.
142
-
143
- ---
144
-
145
- ## 사용법
146
-
147
- ### Claude Code
148
-
149
- 네 훅 모두 자동으로 돕니다 — `SessionStart`는 핸드오프 있으면 짧은 힌트 노출, `UserPromptSubmit`은 프롬프트가 저장된 키워드와 일치하면 전체 컨텍스트 자동 로드, `PreCompact`는 압축 전 저장, `Stop`은 핸드오프가 오래됐을 때 경고. 생성된 문서는 `.claude/handoff.md`에 저장됩니다.
150
-
151
- **수동 체크포인트:**
152
- ```
153
- /handoff-save
154
- ```
155
-
156
- **수동 복원 (키워드 매칭이 안 됐을 경우):**
157
- ```
158
- /handoff-resume
159
- ```
160
-
161
- **과거 세션 검색:**
162
- ```
163
- /handoff-search <주제>
164
- ```
165
-
166
- ### Codex
167
-
168
- 같은 세 훅이 `.codex/hooks.json`으로 자동 실행됩니다. 슬래시 명령어 없음 — 훅이 모두 처리.
169
-
170
- | 이벤트 | 동작 |
171
- |--------|------|
172
- | `SessionStart` | `.claude/handoff.md`를 읽어 컨텍스트로 주입 |
173
- | `PreCompact` | 압축 전 `handoff-drafter` 서브에이전트에 위임 지시 |
174
- | `Stop` | 핸드오프가 오래됐거나 없으면 경고 |
175
-
176
- ### 출력 형식
177
-
178
- ```markdown
179
- # Session Handoff Snapshot
180
- > **Generated:** 2026. 6. 22. 오후 3:30:00
181
-
182
- ## 🎯 High-Level Objective
183
- * **Goal:** Supabase + Notion 주식 데이터 실시간 동기화 Next.js 15 앱 구축
184
- * **Core Intent:** Zustand 스토어로 클라이언트 재요청 최소화 — 비용 절감
185
-
186
- ## 📌 Current State & Next Steps
187
- * **Status:** Task 3 (Zustand 스토어) 완료
188
- * **Blocker:** Notion API rate limit (3 req/s) — 버퍼 레이어 필요
189
- * **Next Action:** Supabase Edge Functions 디바운스 큐 구현
190
-
191
- ## 🛠️ Modified Files Delta
192
- * src/store/stockStore.ts: Zustand 스토어 뼈대 + syncStatus 상태 정의
193
- * src/app/api/notion/sync/route.ts: POST 핸들러 작성 완료, Supabase 미연결
194
-
195
- ## 🚫 Failed Approaches (DO NOT RETRY)
196
- * Approach: Server Actions에서 Notion API 직접 호출 → Result: 리렌더 시 rate limit 즉시 터짐 → Lesson: 큐 미들웨어 필수
197
- * Approach: useEffect 주기 폴링 → Result: Supabase 읽기 사용량 급증 → Lesson: 폐기
198
-
199
- ## 🔑 Crucial Context & Implicit Rules
200
- * Stack: Next.js 15 (App Router), Supabase v2, Zustand v5
201
- * Naming: API 엔드포인트 항상 route.ts, 스토어 PascalCase
202
- * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY 사용 중
203
-
204
- ---
205
- *세션 시작 시 짧은 힌트만 노출됩니다. 전체 컨텍스트는 다음 프롬프트가 위 키워드와 일치할 때, 또는 수동 `/handoff-resume`으로 로드됩니다.*
206
- ```
207
-
208
- ---
209
-
210
- ## 라이선스
211
-
212
- MIT
1
+ # claude-context-auto-handoff
2
+
3
+ **[English](README.md)** | 한국어
4
+
5
+ 컨텍스트 압축이나 세션 종료 직전, 다음 세션이 현재 맥락을 그대로 이어받도록 토큰 효율적인 핸드오프 문서를 자동으로 써 두는 Claude Code 플러그인.
6
+
7
+ ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
8
+ ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
9
+
10
+ ---
11
+
12
+ ## 필수 요구사항
13
+
14
+ - **Node.js 18+** — `node` 명령어가 `PATH`에 있어야 함
15
+ - **Claude Code** 또는 **Codex** — 플러그인 및 훅 실행에 Claude Code CLI 또는 Codex CLI 필요
16
+
17
+ ---
18
+
19
+ ## 개요
20
+
21
+ Claude의 컨텍스트 창이 가득 차면 대화가 자동으로 압축됩니다. 이때 방금 내린 설계 결정, 해결 중이던 버그, 다음 할 일이 흐릿해집니다. 이 플러그인은 `PreCompact`와 `Stop` 이벤트를 감지해 압축 전에 AI가 직접 핸드오프 문서를 씁니다. 다음 세션은 그 파일 하나로 즉시 이어집니다.
22
+
23
+ 핸드오프 내용은 **텔레그래피즘**(관사·군더더기·코드 스니펫 없음)으로 작성해 토큰은 아끼면서도 다음 세션에 필요한 결정 맥락은 그대로 남깁니다.
24
+
25
+ 초안 작성(1회 저장당 3-6k 토큰 규모)은 Haiku 서브에이전트에 위임되며, 서브에이전트가 `generate_handoff_manifest` 호출까지 직접 수행합니다 — 초안이 메인 세션 모델 컨텍스트를 거치지 않습니다.
26
+
27
+ ---
28
+
29
+ ## 구성 요소
30
+
31
+ ### 도구 (Tools)
32
+
33
+ - **`generate_handoff_manifest`** — 현재 프로젝트의 `.claude/handoff.md`에 구조화된 핸드오프 문서를 저장합니다. `.claude/handoffs/{YYYY-MM-DD}/handoff-{timestamp}.md`에도 아카이브됩니다 (최근 50개 파일만 유지, 자동 정리). 동시에 `.claude/handoffs/index.md`에 한 줄 요약(날짜, 키워드, 헤드라인, 경로)을 upsert해 — 아카이브 파일을 전부 열지 않고도 grep 한 번으로 과거 세션을 찾을 수 있는 경량 인덱스를 유지합니다. 한 세션 안에서 여러 번 저장돼도(예: 긴 세션에서 `PreCompact`와 `Stop`이 둘 다 발동) 새 파일을 쌓지 않고 그 세션의 아카이브 파일·인덱스 줄을 그대로 갱신합니다 — MCP 서버 프로세스 하나당 세션ID 하나를 부여해 frontmatter `session:` 필드에 기록합니다.
34
+
35
+ | 파라미터 | 타입 | 필수 | 설명 |
36
+ |----------|------|------|------|
37
+ | `nextSteps` | `string[]` | ✅ | 다음 세션에서 즉시 이어받을 할 일 목록 |
38
+ | `summary` | `string` | ✗ | 간결한 세션 요약 (텔레그래피즘) — 다른 필드로 충분하면 생략 |
39
+ | `taskDescription` | `string` | ✗ | 상위 목표 + 핵심 의도 (왜 중요한가) |
40
+ | `currentStatus` | `string` | ✗ | 완료된 것 vs 남은 것 — 무엇이 아닌 왜를 명시 |
41
+ | `keyDecisions` | `string[]` | ✗ | 아키텍처 결정과 이유. 형식: `"Decision: X — Reason: Y"` |
42
+ | `failedApproaches` | `string[]` | ✗ | 이미 실패한 시도. 형식: `"Approach: X → Result: Y → Lesson: Z"` |
43
+ | `modifiedFiles` | `string[]` | ✗ | 변경 파일과 델타 메모. 형식: `"경로/파일: 무엇을 변경"` — 코드 금지 |
44
+ | `implicitRules` | `string[]` | ✗ | 기술 스택, 네이밍 컨벤션, 환경변수 — 코드에서 유추 불가한 규칙 |
45
+ | `blockers` | `string` | ✗ | 미해결 에러 또는 막혀 있는 문제 |
46
+ | `workingDirectory` | `string` | ✗ | handoff.md를 쓸 프로젝트 루트 절대 경로 — Windows에서 `process.cwd()`가 System32를 가리킬 때 필요 |
47
+
48
+ ### 스킬 (Skills)
49
+
50
+ | 명령어 | 동작 |
51
+ |--------|------|
52
+ | `/handoff-save` | Haiku 서브에이전트에 위임 — 세션 컨텍스트 초안 작성 + `generate_handoff_manifest` 호출까지 직접 수행 (3-6k 토큰 초안이 비싼 메인 모델을 거치지 않음) |
53
+ | `/handoff-resume` | `.claude/handoff.md` 읽어 새 세션에서 컨텍스트 복원 |
54
+ | `/handoff-search` | `.claude/handoffs/index.md`를 grep해 주제와 일치하는 과거 세션 검색 — DB·임베딩 없음 |
55
+
56
+ ### 훅 (Hooks)
57
+
58
+ Claude Code 훅은 기본 내장. Codex 훅은 `templates/.codex`를 프로젝트 루트에 복사해야 활성화됩니다 ([Codex 설치](#codex) 참조).
59
+
60
+ | 이벤트 | 동작 |
61
+ |--------|------|
62
+ | `PreCompact` | 컨텍스트 압축 직전 `handoff-save` 스킬(Haiku 서브에이전트) 호출 지시 |
63
+ | `Stop` | 핸드오프 파일이 오래됐거나 없으면 경고 |
64
+ | `SessionStart` | 핸드오프 존재 시 짧은 힌트(경과 시간, 주제)만 노출 — 전체 내용은 키워드 매칭이나 `/handoff-resume`으로 로드 |
65
+ | `UserPromptSubmit` | 프롬프트가 직전 핸드오프의 키워드와 일치하면 전체 컨텍스트 자동 주입 |
66
+
67
+ ---
68
+
69
+ ## 빠른 시작
70
+
71
+ **Linux / macOS**
72
+ ```bash
73
+ curl -fsSL https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.sh | bash
74
+ # Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md):
75
+ curl -fsSL https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.sh | bash -s -- --codex
76
+ ```
77
+
78
+ **Windows (PowerShell)**
79
+ ```powershell
80
+ irm https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.ps1 -OutFile setup.ps1
81
+ .\setup.ps1 # Claude Code만
82
+ .\setup.ps1 -Codex # Codex도 함께 설정 (훅 + handoff-drafter 서브에이전트 + AGENTS.md)
83
+ ```
84
+
85
+ **npm (크로스플랫폼)**
86
+ ```bash
87
+ npm install -g claude-context-auto-handoff
88
+ claude-context-handoff-setup # Claude Code만
89
+ claude-context-handoff-setup --codex # Codex도 함께 설정
90
+ ```
91
+
92
+ ---
93
+
94
+ ## 설치
95
+
96
+ ### Claude Code 플러그인으로 설치
97
+
98
+ ```bash
99
+ claude plugin install claude-context-auto-handoff
100
+ ```
101
+
102
+ ### npm 패키지로 설치
103
+
104
+ ```bash
105
+ npm install -g claude-context-auto-handoff
106
+ claude-context-handoff-setup # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
107
+ ```
108
+
109
+ ### MCP 수동 설정 (Claude Code)
110
+
111
+ Claude Code `settings.json`에 추가:
112
+
113
+ ```json
114
+ {
115
+ "mcpServers": {
116
+ "context-handoff-manager": {
117
+ "command": "node",
118
+ "args": ["/path/to/build/index.js"]
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ ### Codex
125
+
126
+ `~/.codex/config.toml`에 추가 (전역 MCP 설정):
127
+
128
+ ```toml
129
+ [mcp_servers.context-handoff]
130
+ command = "node"
131
+ args = ["/path/to/build/index.js"]
132
+ ```
133
+
134
+ 그런 다음 훅 템플릿과 지시문을 프로젝트 루트에 복사:
135
+
136
+ ```bash
137
+ cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
138
+ cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
139
+ ```
140
+
141
+ Claude Code와 동일한 `SessionStart`, `PreCompact`, `Stop` 훅이 활성화되고, 핸드오프 초안 작성+저장을 메인 스레드 밖에서 처리하는 `handoff-drafter` 서브에이전트(`.codex/agents/handoff-drafter.toml`)도 함께 활성화됩니다.
142
+
143
+ ---
144
+
145
+ ## 사용법
146
+
147
+ ### Claude Code
148
+
149
+ 네 훅 모두 자동으로 돕니다 — `SessionStart`는 핸드오프 있으면 짧은 힌트 노출, `UserPromptSubmit`은 프롬프트가 저장된 키워드와 일치하면 전체 컨텍스트 자동 로드, `PreCompact`는 압축 전 저장, `Stop`은 핸드오프가 오래됐을 때 경고. 생성된 문서는 `.claude/handoff.md`에 저장됩니다.
150
+
151
+ **수동 체크포인트:**
152
+ ```
153
+ /handoff-save
154
+ ```
155
+
156
+ **수동 복원 (키워드 매칭이 안 됐을 경우):**
157
+ ```
158
+ /handoff-resume
159
+ ```
160
+
161
+ **과거 세션 검색:**
162
+ ```
163
+ /handoff-search <주제>
164
+ ```
165
+
166
+ ### Codex
167
+
168
+ 같은 세 훅이 `.codex/hooks.json`으로 자동 실행됩니다. 슬래시 명령어 없음 — 훅이 모두 처리.
169
+
170
+ | 이벤트 | 동작 |
171
+ |--------|------|
172
+ | `SessionStart` | `.claude/handoff.md`를 읽어 컨텍스트로 주입 |
173
+ | `PreCompact` | 압축 전 `handoff-drafter` 서브에이전트에 위임 지시 |
174
+ | `Stop` | 핸드오프가 오래됐거나 없으면 경고 |
175
+
176
+ ### 출력 형식
177
+
178
+ ```markdown
179
+ # Session Handoff Snapshot
180
+ > **Generated:** 2026. 6. 22. 오후 3:30:00
181
+
182
+ ## 🎯 High-Level Objective
183
+ * **Goal:** Supabase + Notion 주식 데이터 실시간 동기화 Next.js 15 앱 구축
184
+ * **Core Intent:** Zustand 스토어로 클라이언트 재요청 최소화 — 비용 절감
185
+
186
+ ## 📌 Current State & Next Steps
187
+ * **Status:** Task 3 (Zustand 스토어) 완료
188
+ * **Blocker:** Notion API rate limit (3 req/s) — 버퍼 레이어 필요
189
+ * **Next Action:** Supabase Edge Functions 디바운스 큐 구현
190
+
191
+ ## 🛠️ Modified Files Delta
192
+ * src/store/stockStore.ts: Zustand 스토어 뼈대 + syncStatus 상태 정의
193
+ * src/app/api/notion/sync/route.ts: POST 핸들러 작성 완료, Supabase 미연결
194
+
195
+ ## 🚫 Failed Approaches (DO NOT RETRY)
196
+ * Approach: Server Actions에서 Notion API 직접 호출 → Result: 리렌더 시 rate limit 즉시 터짐 → Lesson: 큐 미들웨어 필수
197
+ * Approach: useEffect 주기 폴링 → Result: Supabase 읽기 사용량 급증 → Lesson: 폐기
198
+
199
+ ## 🔑 Crucial Context & Implicit Rules
200
+ * Stack: Next.js 15 (App Router), Supabase v2, Zustand v5
201
+ * Naming: API 엔드포인트 항상 route.ts, 스토어 PascalCase
202
+ * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY 사용 중
203
+
204
+ ---
205
+ *세션 시작 시 짧은 힌트만 노출됩니다. 전체 컨텍스트는 다음 프롬프트가 위 키워드와 일치할 때, 또는 수동 `/handoff-resume`으로 로드됩니다.*
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 라이선스
211
+
212
+ MIT
package/README.md CHANGED
@@ -1,212 +1,212 @@
1
- # claude-context-auto-handoff
2
-
3
- English | **[한국어](README.ko.md)**
4
-
5
- Claude Code plugin that automatically saves session context and generates token-efficient handoff manifests before Claude compacts or stops.
6
-
7
- ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
8
- ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
9
-
10
- ---
11
-
12
- ## Requirements
13
-
14
- - **Node.js 18+** — must be on `PATH` as `node`
15
- - **Claude Code** or **Codex** — plugin and hooks require Claude Code CLI or Codex CLI
16
-
17
- ---
18
-
19
- ## Overview
20
-
21
- 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.
22
-
23
- 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.
24
-
25
- Drafting (typically 3-6k tokens per save) is delegated to a Haiku subagent, which also calls `generate_handoff_manifest` itself — the draft never round-trips through the main-session model.
26
-
27
- ---
28
-
29
- ## Components
30
-
31
- ### Tools
32
-
33
- - **`generate_handoff_manifest`** — Writes a structured `.claude/handoff.md` to the current project directory. Also archives to `.claude/handoffs/{YYYY-MM-DD}/handoff-{timestamp}.md` (auto-pruned to the most recent 50 archive files) and upserts a one-line entry in `.claude/handoffs/index.md` — a compact, grep-friendly index (date, keywords, headline, path) for searching past handoffs without opening every archive file. Repeat saves within the same session (e.g. both `PreCompact` and `Stop` firing in one long session) update that session's own archive file and index line in place instead of piling up near-duplicates — each MCP server process gets one session id, tagged in the `session:` frontmatter field.
34
-
35
- | Parameter | Type | Required | Description |
36
- |-----------|------|----------|-------------|
37
- | `nextSteps` | `string[]` | ✅ | Ordered todo list for the next session |
38
- | `summary` | `string` | ✗ | Terse session recap (telegraphese) — omit if other fields cover it |
39
- | `taskDescription` | `string` | ✗ | High-level goal + core intent (why this matters) |
40
- | `currentStatus` | `string` | ✗ | What is done vs what remains — state why, not just what |
41
- | `keyDecisions` | `string[]` | ✗ | Architecture choices and reasons. Format: `"Decision: X — Reason: Y"` |
42
- | `failedApproaches` | `string[]` | ✗ | Already-failed attempts. Format: `"Approach: X → Result: Y → Lesson: Z"` |
43
- | `modifiedFiles` | `string[]` | ✗ | Changed files with delta notes. Format: `"path/to/file: what changed"` — no code |
44
- | `implicitRules` | `string[]` | ✗ | Tech stack, naming conventions, env vars — anything not derivable from reading code |
45
- | `blockers` | `string` | ✗ | Unresolved errors or open questions |
46
- | `workingDirectory` | `string` | ✗ | Absolute path to the project root to write handoff.md to — needed on Windows where `process.cwd()` may resolve to System32 |
47
-
48
- ### Skills
49
-
50
- | Command | Behavior |
51
- |---------|----------|
52
- | `/handoff-save` | Delegate to a Haiku subagent that drafts session context and calls `generate_handoff_manifest` itself — keeps the 3-6k token draft off the (usually pricier) main-session model |
53
- | `/handoff-resume` | Read `.claude/handoff.md` and restore context in a new session |
54
- | `/handoff-search` | Grep `.claude/handoffs/index.md` for a topic and surface matching past sessions — no database, no embeddings |
55
-
56
- ### Hooks
57
-
58
- Claude Code hooks are built-in. Codex hooks require copying `templates/.codex` to your project root (see [Codex installation](#codex)).
59
-
60
- | Event | Behavior |
61
- |-------|----------|
62
- | `PreCompact` | Prompts the model to invoke the `handoff-save` skill (Haiku subagent) before context compression |
63
- | `Stop` | Warns if handoff is stale or missing after each response |
64
- | `SessionStart` | Surfaces a short hint (age, topics) if a handoff exists — full content loads via keyword match or `/handoff-resume` |
65
- | `UserPromptSubmit` | If your prompt matches a keyword from the last handoff, injects the full handoff content as context automatically |
66
-
67
- ---
68
-
69
- ## Quick Start
70
-
71
- **Linux / macOS**
72
- ```bash
73
- curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
74
- # Also set up Codex (hooks + handoff-drafter subagent + AGENTS.md):
75
- curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash -s -- --codex
76
- ```
77
-
78
- **Windows (PowerShell)**
79
- ```powershell
80
- irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 -OutFile setup.ps1
81
- .\setup.ps1 # Claude Code only
82
- .\setup.ps1 -Codex # also set up Codex (hooks + handoff-drafter subagent + AGENTS.md)
83
- ```
84
-
85
- **npm (cross-platform)**
86
- ```bash
87
- npm install -g claude-context-auto-handoff
88
- claude-context-handoff-setup # Claude Code only
89
- claude-context-handoff-setup --codex # also set up Codex
90
- ```
91
-
92
- ---
93
-
94
- ## Installation
95
-
96
- ### As a Claude Code plugin
97
-
98
- ```bash
99
- claude plugin install claude-context-auto-handoff
100
- ```
101
-
102
- ### As an npm package
103
-
104
- ```bash
105
- npm install -g claude-context-auto-handoff
106
- claude-context-handoff-setup # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
107
- ```
108
-
109
- ### Manual MCP configuration (Claude Code)
110
-
111
- Add to your Claude Code `settings.json`:
112
-
113
- ```json
114
- {
115
- "mcpServers": {
116
- "context-handoff-manager": {
117
- "command": "node",
118
- "args": ["/path/to/build/index.js"]
119
- }
120
- }
121
- }
122
- ```
123
-
124
- ### Codex
125
-
126
- Add to `~/.codex/config.toml` (global MCP config):
127
-
128
- ```toml
129
- [mcp_servers.context-handoff]
130
- command = "node"
131
- args = ["/path/to/build/index.js"]
132
- ```
133
-
134
- Then copy the hook templates and instructions to your project root:
135
-
136
- ```bash
137
- cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
138
- cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
139
- ```
140
-
141
- 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.
142
-
143
- ---
144
-
145
- ## Usage
146
-
147
- ### Claude Code
148
-
149
- All four hooks fire automatically — `SessionStart` surfaces a short hint if a handoff exists, `UserPromptSubmit` auto-loads full context when your prompt matches a saved keyword, `PreCompact` saves before compression, `Stop` warns if handoff is stale. Generated manifests are saved to `.claude/handoff.md`.
150
-
151
- **Manual checkpoint:**
152
- ```
153
- /handoff-save
154
- ```
155
-
156
- **Manual resume (if keyword match didn't trigger):**
157
- ```
158
- /handoff-resume
159
- ```
160
-
161
- **Search past sessions:**
162
- ```
163
- /handoff-search <topic>
164
- ```
165
-
166
- ### Codex
167
-
168
- Same three hooks fire automatically via `.codex/hooks.json`. No slash commands — hooks handle everything.
169
-
170
- | Event | Behavior |
171
- |-------|----------|
172
- | `SessionStart` | Reads `.claude/handoff.md` and injects content as context |
173
- | `PreCompact` | Prompts Codex to delegate to the `handoff-drafter` subagent before compression |
174
- | `Stop` | Warns if handoff is stale (>5 min) or missing |
175
-
176
- ### Output format
177
-
178
- ```markdown
179
- # Session Handoff Snapshot
180
- > **Generated:** 6/22/2026, 3:30:00 PM
181
-
182
- ## 🎯 High-Level Objective
183
- * **Goal:** Build Next.js 15 app syncing Supabase + Notion stock data in real-time
184
- * **Core Intent:** Minimize client re-fetches via Zustand store — cost control
185
-
186
- ## 📌 Current State & Next Steps
187
- * **Status:** Task 3 (Zustand store) complete
188
- * **Blocker:** Notion API rate limit (3 req/s) — buffer layer needed
189
- * **Next Action:** Implement Supabase Edge Functions debounce queue
190
-
191
- ## 🛠️ Modified Files Delta
192
- * src/store/stockStore.ts: Zustand store skeleton + syncStatus state
193
- * src/app/api/notion/sync/route.ts: POST handler written, Supabase not wired yet
194
-
195
- ## 🚫 Failed Approaches (DO NOT RETRY)
196
- * Approach: Call Notion API directly from Server Actions → Result: Rate limit hit on re-render → Lesson: Queue middleware mandatory
197
- * Approach: useEffect polling → Result: Supabase read usage spike → Lesson: Abandoned
198
-
199
- ## 🔑 Crucial Context & Implicit Rules
200
- * Stack: Next.js 15 (App Router), Supabase v2, Zustand v5
201
- * Naming: API endpoints always route.ts, PascalCase store names
202
- * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY active
203
-
204
- ---
205
- *A short hint surfaces on session start; full context loads only if your next prompt matches a keyword above, or via manual `/handoff-resume`.*
206
- ```
207
-
208
- ---
209
-
210
- ## License
211
-
212
- MIT
1
+ # claude-context-auto-handoff
2
+
3
+ English | **[한국어](README.ko.md)**
4
+
5
+ Claude Code plugin that automatically saves session context and generates token-efficient handoff manifests before Claude compacts or stops.
6
+
7
+ ![npm version](https://img.shields.io/npm/v/claude-context-auto-handoff)
8
+ ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
9
+
10
+ ---
11
+
12
+ ## Requirements
13
+
14
+ - **Node.js 18+** — must be on `PATH` as `node`
15
+ - **Claude Code** or **Codex** — plugin and hooks require Claude Code CLI or Codex CLI
16
+
17
+ ---
18
+
19
+ ## Overview
20
+
21
+ 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.
22
+
23
+ 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.
24
+
25
+ Drafting (typically 3-6k tokens per save) is delegated to a Haiku subagent, which also calls `generate_handoff_manifest` itself — the draft never round-trips through the main-session model.
26
+
27
+ ---
28
+
29
+ ## Components
30
+
31
+ ### Tools
32
+
33
+ - **`generate_handoff_manifest`** — Writes a structured `.claude/handoff.md` to the current project directory. Also archives to `.claude/handoffs/{YYYY-MM-DD}/handoff-{timestamp}.md` (auto-pruned to the most recent 50 archive files) and upserts a one-line entry in `.claude/handoffs/index.md` — a compact, grep-friendly index (date, keywords, headline, path) for searching past handoffs without opening every archive file. Repeat saves within the same session (e.g. both `PreCompact` and `Stop` firing in one long session) update that session's own archive file and index line in place instead of piling up near-duplicates — each MCP server process gets one session id, tagged in the `session:` frontmatter field.
34
+
35
+ | Parameter | Type | Required | Description |
36
+ |-----------|------|----------|-------------|
37
+ | `nextSteps` | `string[]` | ✅ | Ordered todo list for the next session |
38
+ | `summary` | `string` | ✗ | Terse session recap (telegraphese) — omit if other fields cover it |
39
+ | `taskDescription` | `string` | ✗ | High-level goal + core intent (why this matters) |
40
+ | `currentStatus` | `string` | ✗ | What is done vs what remains — state why, not just what |
41
+ | `keyDecisions` | `string[]` | ✗ | Architecture choices and reasons. Format: `"Decision: X — Reason: Y"` |
42
+ | `failedApproaches` | `string[]` | ✗ | Already-failed attempts. Format: `"Approach: X → Result: Y → Lesson: Z"` |
43
+ | `modifiedFiles` | `string[]` | ✗ | Changed files with delta notes. Format: `"path/to/file: what changed"` — no code |
44
+ | `implicitRules` | `string[]` | ✗ | Tech stack, naming conventions, env vars — anything not derivable from reading code |
45
+ | `blockers` | `string` | ✗ | Unresolved errors or open questions |
46
+ | `workingDirectory` | `string` | ✗ | Absolute path to the project root to write handoff.md to — needed on Windows where `process.cwd()` may resolve to System32 |
47
+
48
+ ### Skills
49
+
50
+ | Command | Behavior |
51
+ |---------|----------|
52
+ | `/handoff-save` | Delegate to a Haiku subagent that drafts session context and calls `generate_handoff_manifest` itself — keeps the 3-6k token draft off the (usually pricier) main-session model |
53
+ | `/handoff-resume` | Read `.claude/handoff.md` and restore context in a new session |
54
+ | `/handoff-search` | Grep `.claude/handoffs/index.md` for a topic and surface matching past sessions — no database, no embeddings |
55
+
56
+ ### Hooks
57
+
58
+ Claude Code hooks are built-in. Codex hooks require copying `templates/.codex` to your project root (see [Codex installation](#codex)).
59
+
60
+ | Event | Behavior |
61
+ |-------|----------|
62
+ | `PreCompact` | Prompts the model to invoke the `handoff-save` skill (Haiku subagent) before context compression |
63
+ | `Stop` | Warns if handoff is stale or missing after each response |
64
+ | `SessionStart` | Surfaces a short hint (age, topics) if a handoff exists — full content loads via keyword match or `/handoff-resume` |
65
+ | `UserPromptSubmit` | If your prompt matches a keyword from the last handoff, injects the full handoff content as context automatically |
66
+
67
+ ---
68
+
69
+ ## Quick Start
70
+
71
+ **Linux / macOS**
72
+ ```bash
73
+ curl -fsSL https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.sh | bash
74
+ # Also set up Codex (hooks + handoff-drafter subagent + AGENTS.md):
75
+ curl -fsSL https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.sh | bash -s -- --codex
76
+ ```
77
+
78
+ **Windows (PowerShell)**
79
+ ```powershell
80
+ irm https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.ps1 -OutFile setup.ps1
81
+ .\setup.ps1 # Claude Code only
82
+ .\setup.ps1 -Codex # also set up Codex (hooks + handoff-drafter subagent + AGENTS.md)
83
+ ```
84
+
85
+ **npm (cross-platform)**
86
+ ```bash
87
+ npm install -g claude-context-auto-handoff
88
+ claude-context-handoff-setup # Claude Code only
89
+ claude-context-handoff-setup --codex # also set up Codex
90
+ ```
91
+
92
+ ---
93
+
94
+ ## Installation
95
+
96
+ ### As a Claude Code plugin
97
+
98
+ ```bash
99
+ claude plugin install claude-context-auto-handoff
100
+ ```
101
+
102
+ ### As an npm package
103
+
104
+ ```bash
105
+ npm install -g claude-context-auto-handoff
106
+ claude-context-handoff-setup # hooks.json 자동 배치, --codex 붙이면 Codex도 함께 설정
107
+ ```
108
+
109
+ ### Manual MCP configuration (Claude Code)
110
+
111
+ Add to your Claude Code `settings.json`:
112
+
113
+ ```json
114
+ {
115
+ "mcpServers": {
116
+ "context-handoff-manager": {
117
+ "command": "node",
118
+ "args": ["/path/to/build/index.js"]
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ ### Codex
125
+
126
+ Add to `~/.codex/config.toml` (global MCP config):
127
+
128
+ ```toml
129
+ [mcp_servers.context-handoff]
130
+ command = "node"
131
+ args = ["/path/to/build/index.js"]
132
+ ```
133
+
134
+ Then copy the hook templates and instructions to your project root:
135
+
136
+ ```bash
137
+ cp -r /path/to/claude-context-auto-handoff/templates/.codex ./.codex
138
+ cp /path/to/claude-context-auto-handoff/templates/AGENTS.md ./AGENTS.md
139
+ ```
140
+
141
+ 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.
142
+
143
+ ---
144
+
145
+ ## Usage
146
+
147
+ ### Claude Code
148
+
149
+ All four hooks fire automatically — `SessionStart` surfaces a short hint if a handoff exists, `UserPromptSubmit` auto-loads full context when your prompt matches a saved keyword, `PreCompact` saves before compression, `Stop` warns if handoff is stale. Generated manifests are saved to `.claude/handoff.md`.
150
+
151
+ **Manual checkpoint:**
152
+ ```
153
+ /handoff-save
154
+ ```
155
+
156
+ **Manual resume (if keyword match didn't trigger):**
157
+ ```
158
+ /handoff-resume
159
+ ```
160
+
161
+ **Search past sessions:**
162
+ ```
163
+ /handoff-search <topic>
164
+ ```
165
+
166
+ ### Codex
167
+
168
+ Same three hooks fire automatically via `.codex/hooks.json`. No slash commands — hooks handle everything.
169
+
170
+ | Event | Behavior |
171
+ |-------|----------|
172
+ | `SessionStart` | Reads `.claude/handoff.md` and injects content as context |
173
+ | `PreCompact` | Prompts Codex to delegate to the `handoff-drafter` subagent before compression |
174
+ | `Stop` | Warns if handoff is stale (>5 min) or missing |
175
+
176
+ ### Output format
177
+
178
+ ```markdown
179
+ # Session Handoff Snapshot
180
+ > **Generated:** 6/22/2026, 3:30:00 PM
181
+
182
+ ## 🎯 High-Level Objective
183
+ * **Goal:** Build Next.js 15 app syncing Supabase + Notion stock data in real-time
184
+ * **Core Intent:** Minimize client re-fetches via Zustand store — cost control
185
+
186
+ ## 📌 Current State & Next Steps
187
+ * **Status:** Task 3 (Zustand store) complete
188
+ * **Blocker:** Notion API rate limit (3 req/s) — buffer layer needed
189
+ * **Next Action:** Implement Supabase Edge Functions debounce queue
190
+
191
+ ## 🛠️ Modified Files Delta
192
+ * src/store/stockStore.ts: Zustand store skeleton + syncStatus state
193
+ * src/app/api/notion/sync/route.ts: POST handler written, Supabase not wired yet
194
+
195
+ ## 🚫 Failed Approaches (DO NOT RETRY)
196
+ * Approach: Call Notion API directly from Server Actions → Result: Rate limit hit on re-render → Lesson: Queue middleware mandatory
197
+ * Approach: useEffect polling → Result: Supabase read usage spike → Lesson: Abandoned
198
+
199
+ ## 🔑 Crucial Context & Implicit Rules
200
+ * Stack: Next.js 15 (App Router), Supabase v2, Zustand v5
201
+ * Naming: API endpoints always route.ts, PascalCase store names
202
+ * Env: NEXT_PUBLIC_SUPABASE_ANON_KEY active
203
+
204
+ ---
205
+ *A short hint surfaces on session start; full context loads only if your next prompt matches a keyword above, or via manual `/handoff-resume`.*
206
+ ```
207
+
208
+ ---
209
+
210
+ ## License
211
+
212
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-context-auto-handoff",
3
- "version": "1.0.8",
3
+ "version": "1.0.9",
4
4
  "description": "A Claude Code plugin to automate session handoffs before context compaction.",
5
5
  "type": "module",
6
6
  "main": "build/index.js",
package/scripts/setup.ps1 CHANGED
@@ -1,83 +1,83 @@
1
- # context-handoff-mcp-server -- one-line setup for Windows (PowerShell)
2
- # Usage: irm https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.ps1 | iex
3
- # Codex support: run the downloaded file with -Codex, e.g. .\setup.ps1 -Codex
4
-
5
- param(
6
- [switch]$Codex
7
- )
8
-
9
- $ErrorActionPreference = "Stop"
10
-
11
- $PluginName = "claude-context-handoff"
12
- $HooksTarget = "$env:USERPROFILE\.claude\hooks.json"
13
-
14
- Write-Host "[Handoff Setup] Installing $PluginName..."
15
-
16
- # 1. npm global install (builds TypeScript)
17
- npm install -g claude-context-auto-handoff
18
-
19
- $NpmRoot = (npm root -g).Trim()
20
- $PkgRoot = Join-Path $NpmRoot "claude-context-auto-handoff"
21
-
22
- # 2. Register hooks.json (warn if already exists)
23
- $HooksSrc = Join-Path $PkgRoot "hooks\hooks.json"
24
-
25
- if (Test-Path $HooksTarget) {
26
- Write-Host "[Handoff Setup] WARNING: $HooksTarget already exists."
27
- Write-Host " Manually merge contents from: $HooksSrc"
28
- } else {
29
- $HooksDir = Split-Path $HooksTarget
30
- if (-not (Test-Path $HooksDir)) { New-Item -ItemType Directory -Force $HooksDir | Out-Null }
31
- Copy-Item $HooksSrc $HooksTarget
32
- Write-Host "[Handoff Setup] hooks.json registered: $HooksTarget"
33
- }
34
-
35
- if ($Codex) {
36
- Write-Host ""
37
- Write-Host "[Handoff Setup] Configuring Codex..."
38
-
39
- # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
40
- $CodexConfig = "$env:USERPROFILE\.codex\config.toml"
41
- $ServerBin = Join-Path $PkgRoot "build\index.js"
42
- $CodexConfigDir = Split-Path $CodexConfig
43
- if (-not (Test-Path $CodexConfigDir)) { New-Item -ItemType Directory -Force $CodexConfigDir | Out-Null }
44
- if (-not (Test-Path $CodexConfig)) { New-Item -ItemType File -Path $CodexConfig | Out-Null }
45
-
46
- $existingConfig = Get-Content $CodexConfig -Raw -ErrorAction SilentlyContinue
47
- if ($existingConfig -and $existingConfig.Contains("mcp_servers.context-handoff")) {
48
- Write-Host "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CodexConfig — skipping."
49
- } else {
50
- $TomlBlock = @"
51
-
52
- [mcp_servers.context-handoff]
53
- command = "node"
54
- args = ["$($ServerBin.Replace('\','\\'))"]
55
- "@
56
- Add-Content -Path $CodexConfig -Value $TomlBlock
57
- Write-Host "[Handoff Setup] MCP server registered: $CodexConfig"
58
- }
59
-
60
- # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
61
- if (Test-Path ".\.codex") {
62
- Write-Host "[Handoff Setup] WARNING: .\.codex already exists — not overwritten. Reference: $PkgRoot\templates\.codex"
63
- } else {
64
- Copy-Item (Join-Path $PkgRoot "templates\.codex") ".\.codex" -Recurse
65
- Write-Host "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: .\.codex"
66
- }
67
-
68
- if (Test-Path ".\AGENTS.md") {
69
- Write-Host "[Handoff Setup] WARNING: .\AGENTS.md already exists — not overwritten. Reference: $PkgRoot\templates\AGENTS.md"
70
- } else {
71
- Copy-Item (Join-Path $PkgRoot "templates\AGENTS.md") ".\AGENTS.md"
72
- Write-Host "[Handoff Setup] AGENTS.md copied: .\AGENTS.md"
73
- }
74
- }
75
-
76
- Write-Host ""
77
- Write-Host "[Handoff Setup] Done!"
78
- Write-Host ""
79
- Write-Host " Usage:"
80
- Write-Host " /handoff-save -- save current session"
81
- Write-Host " /handoff-resume -- restore previous session"
82
- Write-Host ""
83
- Write-Host " SessionStart hook auto-restores previous context on session open."
1
+ # claude-context-auto-handoff -- one-line setup for Windows (PowerShell)
2
+ # Usage: irm https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.ps1 | iex
3
+ # Codex support: run the downloaded file with -Codex, e.g. .\setup.ps1 -Codex
4
+
5
+ param(
6
+ [switch]$Codex
7
+ )
8
+
9
+ $ErrorActionPreference = "Stop"
10
+
11
+ $PluginName = "claude-context-handoff"
12
+ $HooksTarget = "$env:USERPROFILE\.claude\hooks.json"
13
+
14
+ Write-Host "[Handoff Setup] Installing $PluginName..."
15
+
16
+ # 1. npm global install (builds TypeScript)
17
+ npm install -g claude-context-auto-handoff
18
+
19
+ $NpmRoot = (npm root -g).Trim()
20
+ $PkgRoot = Join-Path $NpmRoot "claude-context-auto-handoff"
21
+
22
+ # 2. Register hooks.json (warn if already exists)
23
+ $HooksSrc = Join-Path $PkgRoot "hooks\hooks.json"
24
+
25
+ if (Test-Path $HooksTarget) {
26
+ Write-Host "[Handoff Setup] WARNING: $HooksTarget already exists."
27
+ Write-Host " Manually merge contents from: $HooksSrc"
28
+ } else {
29
+ $HooksDir = Split-Path $HooksTarget
30
+ if (-not (Test-Path $HooksDir)) { New-Item -ItemType Directory -Force $HooksDir | Out-Null }
31
+ Copy-Item $HooksSrc $HooksTarget
32
+ Write-Host "[Handoff Setup] hooks.json registered: $HooksTarget"
33
+ }
34
+
35
+ if ($Codex) {
36
+ Write-Host ""
37
+ Write-Host "[Handoff Setup] Configuring Codex..."
38
+
39
+ # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
40
+ $CodexConfig = "$env:USERPROFILE\.codex\config.toml"
41
+ $ServerBin = Join-Path $PkgRoot "build\index.js"
42
+ $CodexConfigDir = Split-Path $CodexConfig
43
+ if (-not (Test-Path $CodexConfigDir)) { New-Item -ItemType Directory -Force $CodexConfigDir | Out-Null }
44
+ if (-not (Test-Path $CodexConfig)) { New-Item -ItemType File -Path $CodexConfig | Out-Null }
45
+
46
+ $existingConfig = Get-Content $CodexConfig -Raw -ErrorAction SilentlyContinue
47
+ if ($existingConfig -and $existingConfig.Contains("mcp_servers.context-handoff")) {
48
+ Write-Host "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CodexConfig — skipping."
49
+ } else {
50
+ $TomlBlock = @"
51
+
52
+ [mcp_servers.context-handoff]
53
+ command = "node"
54
+ args = ["$($ServerBin.Replace('\','\\'))"]
55
+ "@
56
+ Add-Content -Path $CodexConfig -Value $TomlBlock
57
+ Write-Host "[Handoff Setup] MCP server registered: $CodexConfig"
58
+ }
59
+
60
+ # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
61
+ if (Test-Path ".\.codex") {
62
+ Write-Host "[Handoff Setup] WARNING: .\.codex already exists — not overwritten. Reference: $PkgRoot\templates\.codex"
63
+ } else {
64
+ Copy-Item (Join-Path $PkgRoot "templates\.codex") ".\.codex" -Recurse
65
+ Write-Host "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: .\.codex"
66
+ }
67
+
68
+ if (Test-Path ".\AGENTS.md") {
69
+ Write-Host "[Handoff Setup] WARNING: .\AGENTS.md already exists — not overwritten. Reference: $PkgRoot\templates\AGENTS.md"
70
+ } else {
71
+ Copy-Item (Join-Path $PkgRoot "templates\AGENTS.md") ".\AGENTS.md"
72
+ Write-Host "[Handoff Setup] AGENTS.md copied: .\AGENTS.md"
73
+ }
74
+ }
75
+
76
+ Write-Host ""
77
+ Write-Host "[Handoff Setup] Done!"
78
+ Write-Host ""
79
+ Write-Host " Usage:"
80
+ Write-Host " /handoff-save -- save current session"
81
+ Write-Host " /handoff-resume -- restore previous session"
82
+ Write-Host ""
83
+ Write-Host " SessionStart hook auto-restores previous context on session open."
package/scripts/setup.sh CHANGED
@@ -1,82 +1,82 @@
1
- #!/usr/bin/env bash
2
- # context-handoff-mcp-server -- one-line setup for Linux/macOS
3
- # Usage: curl -fsSL https://raw.githubusercontent.com/Ethualo/context-handoff-mcp-server/main/scripts/setup.sh | bash
4
- # Codex support: ... | bash -s -- --codex
5
-
6
- set -e
7
-
8
- PLUGIN_NAME="claude-context-handoff"
9
- HOOKS_TARGET="$HOME/.claude/hooks.json"
10
- WITH_CODEX=false
11
-
12
- for arg in "$@"; do
13
- case "$arg" in
14
- --codex) WITH_CODEX=true ;;
15
- esac
16
- done
17
-
18
- echo "[Handoff Setup] Installing $PLUGIN_NAME..."
19
-
20
- # 1. npm global install (builds TypeScript)
21
- npm install -g claude-context-auto-handoff
22
-
23
- PKG_ROOT="$(npm root -g)/claude-context-auto-handoff"
24
-
25
- # 2. Register hooks.json (warn if already exists)
26
- HOOKS_SRC="$PKG_ROOT/hooks/hooks.json"
27
-
28
- if [ -f "$HOOKS_TARGET" ]; then
29
- echo "[Handoff Setup] WARNING: $HOOKS_TARGET already exists."
30
- echo " Manually merge contents from: $HOOKS_SRC"
31
- else
32
- mkdir -p "$(dirname "$HOOKS_TARGET")"
33
- cp "$HOOKS_SRC" "$HOOKS_TARGET"
34
- echo "[Handoff Setup] hooks.json registered: $HOOKS_TARGET"
35
- fi
36
-
37
- if [ "$WITH_CODEX" = true ]; then
38
- echo ""
39
- echo "[Handoff Setup] Configuring Codex..."
40
-
41
- # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
42
- CODEX_CONFIG="$HOME/.codex/config.toml"
43
- SERVER_BIN="$PKG_ROOT/build/index.js"
44
- mkdir -p "$(dirname "$CODEX_CONFIG")"
45
- touch "$CODEX_CONFIG"
46
-
47
- if grep -q "mcp_servers.context-handoff" "$CODEX_CONFIG" 2>/dev/null; then
48
- echo "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CODEX_CONFIG — skipping."
49
- else
50
- {
51
- echo ""
52
- echo "[mcp_servers.context-handoff]"
53
- echo "command = \"node\""
54
- echo "args = [\"$SERVER_BIN\"]"
55
- } >> "$CODEX_CONFIG"
56
- echo "[Handoff Setup] MCP server registered: $CODEX_CONFIG"
57
- fi
58
-
59
- # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
60
- if [ -d "./.codex" ]; then
61
- echo "[Handoff Setup] WARNING: ./.codex already exists — not overwritten. Reference: $PKG_ROOT/templates/.codex"
62
- else
63
- cp -r "$PKG_ROOT/templates/.codex" ./.codex
64
- echo "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: ./.codex"
65
- fi
66
-
67
- if [ -f "./AGENTS.md" ]; then
68
- echo "[Handoff Setup] WARNING: ./AGENTS.md already exists — not overwritten. Reference: $PKG_ROOT/templates/AGENTS.md"
69
- else
70
- cp "$PKG_ROOT/templates/AGENTS.md" ./AGENTS.md
71
- echo "[Handoff Setup] AGENTS.md copied: ./AGENTS.md"
72
- fi
73
- fi
74
-
75
- echo ""
76
- echo "[Handoff Setup] Done!"
77
- echo ""
78
- echo " Usage:"
79
- echo " /handoff-save -- save current session"
80
- echo " /handoff-resume -- restore previous session"
81
- echo ""
82
- echo " SessionStart hook auto-restores previous context on session open."
1
+ #!/usr/bin/env bash
2
+ # claude-context-auto-handoff -- one-line setup for Linux/macOS
3
+ # Usage: curl -fsSL https://raw.githubusercontent.com/Ethualo/claude-context-auto-handoff/main/scripts/setup.sh | bash
4
+ # Codex support: ... | bash -s -- --codex
5
+
6
+ set -e
7
+
8
+ PLUGIN_NAME="claude-context-handoff"
9
+ HOOKS_TARGET="$HOME/.claude/hooks.json"
10
+ WITH_CODEX=false
11
+
12
+ for arg in "$@"; do
13
+ case "$arg" in
14
+ --codex) WITH_CODEX=true ;;
15
+ esac
16
+ done
17
+
18
+ echo "[Handoff Setup] Installing $PLUGIN_NAME..."
19
+
20
+ # 1. npm global install (builds TypeScript)
21
+ npm install -g claude-context-auto-handoff
22
+
23
+ PKG_ROOT="$(npm root -g)/claude-context-auto-handoff"
24
+
25
+ # 2. Register hooks.json (warn if already exists)
26
+ HOOKS_SRC="$PKG_ROOT/hooks/hooks.json"
27
+
28
+ if [ -f "$HOOKS_TARGET" ]; then
29
+ echo "[Handoff Setup] WARNING: $HOOKS_TARGET already exists."
30
+ echo " Manually merge contents from: $HOOKS_SRC"
31
+ else
32
+ mkdir -p "$(dirname "$HOOKS_TARGET")"
33
+ cp "$HOOKS_SRC" "$HOOKS_TARGET"
34
+ echo "[Handoff Setup] hooks.json registered: $HOOKS_TARGET"
35
+ fi
36
+
37
+ if [ "$WITH_CODEX" = true ]; then
38
+ echo ""
39
+ echo "[Handoff Setup] Configuring Codex..."
40
+
41
+ # 3. Register MCP server in ~/.codex/config.toml (warn if entry already exists)
42
+ CODEX_CONFIG="$HOME/.codex/config.toml"
43
+ SERVER_BIN="$PKG_ROOT/build/index.js"
44
+ mkdir -p "$(dirname "$CODEX_CONFIG")"
45
+ touch "$CODEX_CONFIG"
46
+
47
+ if grep -q "mcp_servers.context-handoff" "$CODEX_CONFIG" 2>/dev/null; then
48
+ echo "[Handoff Setup] WARNING: [mcp_servers.context-handoff] already present in $CODEX_CONFIG — skipping."
49
+ else
50
+ {
51
+ echo ""
52
+ echo "[mcp_servers.context-handoff]"
53
+ echo "command = \"node\""
54
+ echo "args = [\"$SERVER_BIN\"]"
55
+ } >> "$CODEX_CONFIG"
56
+ echo "[Handoff Setup] MCP server registered: $CODEX_CONFIG"
57
+ fi
58
+
59
+ # 4. Copy .codex hooks + agents + AGENTS.md into the current project (warn if already present)
60
+ if [ -d "./.codex" ]; then
61
+ echo "[Handoff Setup] WARNING: ./.codex already exists — not overwritten. Reference: $PKG_ROOT/templates/.codex"
62
+ else
63
+ cp -r "$PKG_ROOT/templates/.codex" ./.codex
64
+ echo "[Handoff Setup] Codex hooks + handoff-drafter subagent copied: ./.codex"
65
+ fi
66
+
67
+ if [ -f "./AGENTS.md" ]; then
68
+ echo "[Handoff Setup] WARNING: ./AGENTS.md already exists — not overwritten. Reference: $PKG_ROOT/templates/AGENTS.md"
69
+ else
70
+ cp "$PKG_ROOT/templates/AGENTS.md" ./AGENTS.md
71
+ echo "[Handoff Setup] AGENTS.md copied: ./AGENTS.md"
72
+ fi
73
+ fi
74
+
75
+ echo ""
76
+ echo "[Handoff Setup] Done!"
77
+ echo ""
78
+ echo " Usage:"
79
+ echo " /handoff-save -- save current session"
80
+ echo " /handoff-resume -- restore previous session"
81
+ echo ""
82
+ echo " SessionStart hook auto-restores previous context on session open."