claude-code-handoff 1.1.0 → 1.2.0

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.
package/README.md CHANGED
@@ -1,19 +1,131 @@
1
1
  # claude-code-handoff
2
2
 
3
- Session continuity for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Pick up exactly where you left off — across `/clear`, crashes, or context switches.
3
+ > Session continuity for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
4
+ > Pick up exactly where you left off — across `/clear`, crashes, or context switches.
4
5
 
5
- ## What it does
6
+ [![npm version](https://img.shields.io/npm/v/claude-code-handoff)](https://www.npmjs.com/package/claude-code-handoff)
7
+ [![license](https://img.shields.io/npm/l/claude-code-handoff)](./LICENSE)
6
8
 
7
- Adds 4 slash commands to any Claude Code project:
9
+ ---
10
+
11
+ ## The Problem
12
+
13
+ Claude Code loses all context when you `/clear` or start a new session. Long-running work gets fragmented. You waste tokens re-explaining what you were doing. Switching between features means losing track of the other one.
14
+
15
+ ## The Solution
16
+
17
+ **claude-code-handoff** adds 4 slash commands that give Claude persistent memory:
8
18
 
9
19
  | Command | Description |
10
20
  |---------|-------------|
11
- | `/handoff` | Auto-save session state (no wizard, just save and go) |
12
- | `/resume` | Resume from a saved session (interactive wizard) |
13
- | `/save-handoff` | Save session state with options (interactive wizard) |
21
+ | `/handoff` | Auto-save session state no questions asked |
22
+ | `/resume` | Resume from a saved session interactive picker |
23
+ | `/save-handoff` | Save with options choose where and how |
14
24
  | `/switch-context <topic>` | Switch between parallel workstreams |
15
25
 
16
- Session state is stored in `.claude/handoffs/` (gitignored by default) so each developer keeps their own context.
26
+ Session state is stored in `.claude/handoffs/` (gitignored) each developer keeps their own context, no conflicts.
27
+
28
+ ---
29
+
30
+ ## Quick Start
31
+
32
+ ```bash
33
+ cd your-project
34
+ npx claude-code-handoff
35
+ ```
36
+
37
+ That's it. Open Claude Code and your 4 commands are ready.
38
+
39
+ ---
40
+
41
+ ## How It Works
42
+
43
+ ### Core Flow
44
+
45
+ ```mermaid
46
+ graph LR
47
+ A[Work in Claude Code] --> B["/handoff"]
48
+ B --> C[State saved to _active.md]
49
+ C --> D["/clear"]
50
+ D --> E[New session]
51
+ E --> F["/resume"]
52
+ F --> G[Full context restored]
53
+ G --> A
54
+ ```
55
+
56
+ ### The `/handoff` Command (Auto-Save)
57
+
58
+ No wizard, no questions. Claude analyzes the conversation and saves everything automatically.
59
+
60
+ ```mermaid
61
+ flowchart TD
62
+ A["/handoff"] --> B[Analyze conversation]
63
+ B --> C{_active.md exists?}
64
+ C -->|Yes| D{Same workstream?}
65
+ C -->|No| F[Create new _active.md]
66
+ D -->|Yes| E[Append session to existing]
67
+ D -->|No| G[Archive old → Create new]
68
+ E --> H["✅ Handoff saved. Type /clear then /resume"]
69
+ F --> H
70
+ G --> H
71
+ ```
72
+
73
+ ### The `/resume` Command
74
+
75
+ Interactive wizard that shows all available sessions and lets you pick one.
76
+
77
+ ```mermaid
78
+ flowchart TD
79
+ A["/resume"] --> B[Scan handoffs/]
80
+ B --> C{Handoffs found?}
81
+ C -->|No| D["No handoffs found. Use /handoff to create one."]
82
+ C -->|Yes| E[Present interactive picker]
83
+ E --> F[User selects session]
84
+ F --> G[Load full handoff]
85
+ G --> H[Read key files for context]
86
+ H --> I[Present summary + next steps]
87
+ I --> J[Wait for user instruction]
88
+ ```
89
+
90
+ ### The `/switch-context` Command
91
+
92
+ Manage parallel workstreams without losing state.
93
+
94
+ ```mermaid
95
+ flowchart TD
96
+ A["/switch-context api-refactor"] --> B[Read current _active.md]
97
+ B --> C[Archive current → archive/current-slug.md]
98
+ C --> D{Target exists in archive?}
99
+ D -->|Yes| E[Load target → _active.md]
100
+ D -->|No| F[Create fresh _active.md]
101
+ E --> G[Show target context + next steps]
102
+ F --> G
103
+ ```
104
+
105
+ ### File Architecture
106
+
107
+ ```mermaid
108
+ graph TD
109
+ subgraph ".claude/handoffs/"
110
+ A["_active.md<br/><i>Current workstream (like git HEAD)</i>"]
111
+ subgraph "archive/"
112
+ B["auth-refactor.md"]
113
+ C["api-v2.md"]
114
+ D["bugfix-login.md"]
115
+ end
116
+ end
117
+
118
+ A <-->|"/switch-context"| B
119
+ A <-->|"/switch-context"| C
120
+ A <-->|"/switch-context"| D
121
+
122
+ style A fill:#2d5016,stroke:#4ade80,color:#fff
123
+ style B fill:#1e3a5f,stroke:#60a5fa,color:#fff
124
+ style C fill:#1e3a5f,stroke:#60a5fa,color:#fff
125
+ style D fill:#1e3a5f,stroke:#60a5fa,color:#fff
126
+ ```
127
+
128
+ ---
17
129
 
18
130
  ## Install
19
131
 
@@ -28,104 +140,259 @@ npx claude-code-handoff
28
140
 
29
141
  ```bash
30
142
  cd your-project
31
- curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/install.sh | bash
143
+ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/install.sh | bash
32
144
  ```
33
145
 
34
146
  ### Option C: clone & run
35
147
 
36
148
  ```bash
37
- git clone https://github.com/hugocapitelli/claude-code-handoff.git /tmp/claude-code-handoff
149
+ git clone https://github.com/eximIA-Ventures/claude-code-handoff.git /tmp/claude-code-handoff
38
150
  cd your-project
39
151
  /tmp/claude-code-handoff/install.sh
40
152
  ```
41
153
 
42
- ## What gets installed
154
+ ### What Gets Installed
43
155
 
44
156
  ```
45
157
  your-project/
46
158
  └── .claude/
47
159
  ├── commands/
48
- │ ├── handoff.md # /handoff command (auto-save)
49
- │ ├── resume.md # /resume command
50
- │ ├── save-handoff.md # /save-handoff command
51
- │ └── switch-context.md # /switch-context command
160
+ │ ├── handoff.md /handoff (auto-save)
161
+ │ ├── resume.md /resume (interactive picker)
162
+ │ ├── save-handoff.md /save-handoff (wizard)
163
+ │ └── switch-context.md /switch-context (workstream switch)
52
164
  ├── rules/
53
- │ └── session-continuity.md # Auto-loaded rules for Claude
54
- └── handoffs/ # Session state (gitignored)
55
- ├── _active.md # Current workstream
56
- └── archive/ # Paused workstreams
165
+ │ └── session-continuity.md Auto-loaded behavioral rules
166
+ └── handoffs/ Session state (gitignored)
167
+ ├── _active.md Current workstream
168
+ └── archive/ Paused workstreams
57
169
  ```
58
170
 
59
171
  The installer also:
172
+ - Creates the full `.claude/handoffs/archive/` directory structure
60
173
  - Adds `.claude/handoffs/` to `.gitignore`
61
174
  - Adds a `Session Continuity` section to `.claude/CLAUDE.md` (creates one if missing)
62
175
 
63
- ## Usage
176
+ ---
177
+
178
+ ## Usage Examples
64
179
 
65
- ### Quick save before clearing
180
+ ### Daily workflow
66
181
 
67
182
  ```
68
- > /handoff
69
- # Claude auto-saves current context to .claude/handoffs/_active.md
70
- > /clear
183
+ you: [work on feature for a while]
184
+ you: /handoff
185
+ claude: Handoff saved. 5 actions recorded, 3 next steps.
186
+ You can now type /clear to free context.
187
+ you: /clear
188
+
189
+ ── new session ──
190
+
191
+ you: /resume
192
+ claude: ## Resuming session
193
+ **Workstream:** auth-refactor
194
+ **Last updated:** 2026-02-16
195
+ ### Last session summary
196
+ - Implemented JWT middleware in src/auth/middleware.ts
197
+ - Added refresh token rotation logic
198
+ - Fixed CORS headers for token endpoint
199
+ ### Next steps
200
+ 1. Add unit tests for token rotation
201
+ 2. Update API docs for new auth endpoints
202
+ 3. Test with frontend login flow
203
+ What would you like to do?
71
204
  ```
72
205
 
73
- ### Save with options
206
+ ### Switching between features
74
207
 
75
208
  ```
76
- > /save-handoff
77
- # Interactive wizard: update active, save as new context, or replace
209
+ you: /switch-context payments-v2
210
+ claude: ## Context switched
211
+ **From:** auth-refactor → archived
212
+ **To:** payments-v2
213
+ ### State
214
+ - Last worked on Stripe webhook handler
215
+ - Next: add idempotency keys
216
+ What would you like to do?
78
217
  ```
79
218
 
80
- ### Resume next session
219
+ ### Saving with options
81
220
 
82
221
  ```
83
- > /resume
84
- # Interactive wizard shows available sessions
85
- # Select one → Claude loads full context and shows next steps
222
+ you: /save-handoff
223
+ claude: Where should this session's handoff be saved?
224
+ 1. Update active (auth-refactor)
225
+ 2. Save as new context
226
+ 3. Replace active
86
227
  ```
87
228
 
88
- ### Switch workstreams
229
+ ---
230
+
231
+ ## What Gets Captured
232
+
233
+ The handoff file records everything Claude needs to resume cold:
234
+
235
+ | Section | Purpose |
236
+ |---------|---------|
237
+ | **Active Workstream** | What you're working on (name + description) |
238
+ | **Active Agent(s)** | Any personas active (e.g., @dev, @architect) |
239
+ | **What Was Done** | Session-by-session log with dates |
240
+ | **What's Next** | Prioritized, actionable pending items |
241
+ | **Key Files** | Files to read for context reload |
242
+ | **Current Document** | The main file being worked on |
243
+ | **Decisions Registry** | Architectural/design decisions with rationale |
244
+
245
+ ### Session History
246
+
247
+ Each `/handoff` or `/save-handoff` appends a new session entry. History is preserved — you can see the full timeline of work across sessions:
89
248
 
249
+ ```markdown
250
+ ## What Was Done
251
+
252
+ ### Session 3 (2026-02-16)
253
+ - Added rate limiting to API endpoints
254
+ - Fixed memory leak in WebSocket handler
255
+
256
+ ### Session 2 (2026-02-15)
257
+ - Implemented JWT refresh token rotation
258
+ - Added CORS configuration
259
+
260
+ ### Session 1 (2026-02-14)
261
+ - Set up Express server with TypeScript
262
+ - Created initial route structure
90
263
  ```
91
- > /switch-context auth-refactor
92
- # Archives current session, loads auth-refactor context
264
+
265
+ ---
266
+
267
+ ## Architecture
268
+
269
+ ### Design Principles
270
+
271
+ 1. **`_active.md` is like `HEAD` in git** — it always points to your current workstream. No need to remember filenames.
272
+ 2. **Archive is like branches** — paused workstreams live in `archive/`, ready to be loaded anytime.
273
+ 3. **Append-only history** — sessions are never deleted, only appended. You can always trace what happened.
274
+ 4. **Gitignored by default** — each developer has their own session state, no merge conflicts.
275
+ 5. **Zero dependencies** — the installer is pure bash/Node.js, the commands are plain markdown.
276
+
277
+ ### Command Comparison
278
+
279
+ ```mermaid
280
+ graph TD
281
+ subgraph "Quick Save"
282
+ H["/handoff"]
283
+ H --> H1["No wizard"]
284
+ H --> H2["Auto-detects workstream"]
285
+ H --> H3["Appends or creates"]
286
+ end
287
+
288
+ subgraph "Save with Options"
289
+ S["/save-handoff"]
290
+ S --> S1["Interactive wizard"]
291
+ S --> S2["Choose: update / new / replace"]
292
+ S --> S3["Name your contexts"]
293
+ end
294
+
295
+ subgraph "Resume"
296
+ R["/resume"]
297
+ R --> R1["Lists all sessions"]
298
+ R --> R2["Shows summary per session"]
299
+ R --> R3["Loads key files"]
300
+ end
301
+
302
+ subgraph "Switch"
303
+ SW["/switch-context"]
304
+ SW --> SW1["Archives current"]
305
+ SW --> SW2["Loads target"]
306
+ SW --> SW3["Or creates fresh"]
307
+ end
308
+
309
+ style H fill:#2d5016,stroke:#4ade80,color:#fff
310
+ style S fill:#1e3a5f,stroke:#60a5fa,color:#fff
311
+ style R fill:#5c1e8a,stroke:#c084fc,color:#fff
312
+ style SW fill:#7c2d12,stroke:#fb923c,color:#fff
93
313
  ```
94
314
 
95
- ## How it works
315
+ | | `/handoff` | `/save-handoff` | `/resume` | `/switch-context` |
316
+ |---|---|---|---|---|
317
+ | **When** | Before `/clear` | When you need options | Start of session | Mid-session |
318
+ | **Interactive** | No | Yes (wizard) | Yes (picker) | No (with arg) |
319
+ | **Creates files** | Auto | User chooses | No | Auto |
320
+ | **Reads files** | `_active.md` | `_active.md` + `archive/` | All handoffs | `_active.md` + target |
321
+
322
+ ---
96
323
 
97
- The handoff file (`.claude/handoffs/_active.md`) captures:
324
+ ## Behavioral Rules
98
325
 
99
- - **Active Workstream** what you're working on
100
- - **Active Agent(s)** — which agents/personas are active
101
- - **What Was Done** — session-by-session log of completed work
102
- - **What's Next** — prioritized pending items
103
- - **Key Files** — important files for context reload
104
- - **Decisions Registry** — architectural decisions made
326
+ The installer adds a `session-continuity.md` rules file that Claude auto-loads on every session. This gives Claude awareness of the handoff system without you needing to explain it:
105
327
 
106
- When you `/resume`, Claude reads this file and presents a summary so you can continue exactly where you left off.
328
+ - **On session start**: Claude knows `_active.md` exists but doesn't read it unless asked
329
+ - **During work**: Claude proactively reminds you to save after significant milestones
330
+ - **Command awareness**: Claude understands all 4 commands natively
107
331
 
108
- The `_active.md` file acts like `HEAD` in git — it points to your current workstream. The `archive/` folder holds paused workstreams you can switch to anytime with `/switch-context`.
332
+ ---
109
333
 
110
334
  ## Uninstall
111
335
 
112
336
  ```bash
113
337
  cd your-project
114
- curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/uninstall.sh | bash
338
+ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/uninstall.sh | bash
115
339
  ```
116
340
 
117
- Or manually remove:
341
+ The uninstaller:
342
+ - Removes all 4 command files
343
+ - Removes the rules file
344
+ - Preserves handoff data if sessions exist (won't delete your session history)
345
+ - Cleans `.gitignore` entries
346
+ - Leaves `CLAUDE.md` unchanged (remove the section manually if desired)
347
+
348
+ Or remove manually:
118
349
  ```bash
119
- rm -rf .claude/commands/handoff.md .claude/commands/resume.md .claude/commands/save-handoff.md .claude/commands/switch-context.md
120
- rm -rf .claude/rules/session-continuity.md
121
- rm -rf .claude/handoffs/
350
+ rm .claude/commands/{handoff,resume,save-handoff,switch-context}.md
351
+ rm .claude/rules/session-continuity.md
352
+ rm -rf .claude/handoffs/ # ⚠️ deletes all session history
122
353
  ```
123
354
 
355
+ ---
356
+
124
357
  ## Requirements
125
358
 
126
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
127
- - A project directory with (or without) an existing `.claude/` folder
359
+ - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
360
+ - Any project directory (with or without existing `.claude/` folder)
361
+ - Node.js 18+ (for npx install) or curl (for bash install)
362
+
363
+ ---
364
+
365
+ ## FAQ
366
+
367
+ **Q: Does this work with multiple developers on the same project?**
368
+ A: Yes. Handoff files are gitignored, so each developer has their own session state. No conflicts.
369
+
370
+ **Q: What happens if I forget to `/handoff` before `/clear`?**
371
+ A: The context is lost for that session. The previous handoff is still there — you just won't have the latest session recorded.
372
+
373
+ **Q: Can I have unlimited workstreams?**
374
+ A: Yes. The `archive/` folder has no limit. Each workstream is a single `.md` file.
375
+
376
+ **Q: Does it work with Claude Code agents/personas?**
377
+ A: Yes. The handoff captures which agents are active (e.g., @dev, @architect) so Claude knows the context when resuming.
378
+
379
+ **Q: What if `_active.md` gets too long?**
380
+ A: The commands automatically summarize older sessions into a "Prior Sessions Summary" when the file exceeds ~300 lines.
381
+
382
+ **Q: Can I edit the handoff files manually?**
383
+ A: Absolutely. They're plain markdown. You can add notes, reorder next steps, or clean up history.
384
+
385
+ ---
386
+
387
+ ## Contributing
388
+
389
+ 1. Fork this repo
390
+ 2. Make your changes
391
+ 3. Test by running `./install.sh` in a test project
392
+ 4. Open a PR
393
+
394
+ ---
128
395
 
129
396
  ## License
130
397
 
131
- MIT
398
+ [MIT](./LICENSE) — built by [exímIA Ventures](https://github.com/eximIA-Ventures)
package/install.sh CHANGED
@@ -1,9 +1,9 @@
1
1
  #!/bin/bash
2
2
  # claude-code-handoff — Session continuity for Claude Code
3
- # Install: curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/install.sh | bash
3
+ # Install: curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/install.sh | bash
4
4
  #
5
5
  # Or clone and run:
6
- # git clone https://github.com/hugocapitelli/claude-code-handoff.git /tmp/claude-code-handoff
6
+ # git clone https://github.com/eximIA-Ventures/claude-code-handoff.git /tmp/claude-code-handoff
7
7
  # cd /your/project && /tmp/claude-code-handoff/install.sh
8
8
 
9
9
  set -e
@@ -14,7 +14,7 @@ YELLOW='\033[1;33m'
14
14
  CYAN='\033[0;36m'
15
15
  NC='\033[0m'
16
16
 
17
- REPO="hugocapitelli/claude-code-handoff"
17
+ REPO="eximIA-Ventures/claude-code-handoff"
18
18
  BRANCH="main"
19
19
  RAW_BASE="https://raw.githubusercontent.com/$REPO/$BRANCH"
20
20
  PROJECT_DIR="$(pwd)"
package/package.json CHANGED
@@ -1,10 +1,17 @@
1
1
  {
2
2
  "name": "claude-code-handoff",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Session continuity for Claude Code — 4 slash commands to save, resume, and switch workstreams across /clear",
5
- "bin": {
6
- "claude-code-handoff": "./cli.js"
7
- },
5
+ "bin": "./cli.js",
6
+ "files": [
7
+ "cli.js",
8
+ "install.sh",
9
+ "uninstall.sh",
10
+ "commands/",
11
+ "rules/",
12
+ "LICENSE",
13
+ "README.md"
14
+ ],
8
15
  "keywords": [
9
16
  "claude",
10
17
  "claude-code",
@@ -18,6 +25,6 @@
18
25
  "license": "MIT",
19
26
  "repository": {
20
27
  "type": "git",
21
- "url": "https://github.com/hugocapitelli/claude-code-handoff"
28
+ "url": "https://github.com/eximIA-Ventures/claude-code-handoff"
22
29
  }
23
30
  }
package/uninstall.sh CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/bin/bash
2
2
  # claude-code-handoff — Uninstall
3
- # Usage: curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/uninstall.sh | bash
3
+ # Usage: curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/uninstall.sh | bash
4
4
 
5
5
  set -e
6
6