@honcho-ai/claude-honcho 0.3.3 → 0.4.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.
Files changed (36) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +111 -335
  3. package/dist/hooks/pre-tool-honcho.js +551 -605
  4. package/dist/hooks/pre-tool-honcho.js.map +11 -9
  5. package/dist/hooks/save-user-message.js +1741 -1057
  6. package/dist/hooks/save-user-message.js.map +24 -19
  7. package/dist/hooks/session-end.js +559 -617
  8. package/dist/hooks/session-end.js.map +11 -9
  9. package/dist/hooks/session-start.js +1938 -1304
  10. package/dist/hooks/session-start.js.map +31 -22
  11. package/dist/hooks/stop.js +1785 -1157
  12. package/dist/hooks/stop.js.map +25 -19
  13. package/dist/hooks/user-prompt.js +696 -16571
  14. package/dist/hooks/user-prompt.js.map +13 -90
  15. package/dist/mcp-server.js +1689 -1676
  16. package/dist/mcp-server.js.map +23 -20
  17. package/dist/skills/backfill-runner.js +1824 -911
  18. package/dist/skills/backfill-runner.js.map +27 -20
  19. package/dist/skills/{setup-runner.js → pane-runner.js} +1910 -1020
  20. package/dist/{hooks/pre-compact.js.map → skills/pane-runner.js.map} +28 -24
  21. package/dist/skills/status-runner.js +1568 -753
  22. package/dist/skills/status-runner.js.map +23 -19
  23. package/hooks/hooks.json +10 -42
  24. package/hooks/register.tsx +574 -0
  25. package/package.json +1 -1
  26. package/skills/insights/SKILL.md +3 -7
  27. package/dist/hooks/post-tool-use.js +0 -16905
  28. package/dist/hooks/post-tool-use.js.map +0 -97
  29. package/dist/hooks/pre-compact.js +0 -17087
  30. package/dist/skills/setup-runner.js.map +0 -95
  31. package/scripts/honcho-statusline.sh +0 -101
  32. package/skills/briefing/SKILL.md +0 -20
  33. package/skills/config/SKILL.md +0 -288
  34. package/skills/import/SKILL.md +0 -73
  35. package/skills/setup/SKILL.md +0 -60
  36. package/skills/status/SKILL.md +0 -30
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "honcho",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "description": "Persistent memory for Claude Code sessions using Honcho by Plastic Labs",
5
5
  "author": {
6
6
  "name": "Plastic Labs",
package/README.md CHANGED
@@ -44,86 +44,44 @@ Give Claude Code long-term memory that survives context wipes, session restarts,
44
44
 
45
45
  ## Prerequisites
46
46
 
47
- - A Honcho API key from [app.honcho.dev](https://app.honcho.dev)
47
+ - Claude Code v2.1.287 or later
48
48
  - [Node.js](https://nodejs.org) on your PATH
49
+ - A Honcho account at [app.honcho.dev](https://app.honcho.dev)
49
50
 
50
51
  The plugin ships as a self-contained bundle -- no other dependencies needed.
51
52
 
52
53
  ## Quick Start
53
54
 
54
- ### Step 1: Get Your Honcho API Key
55
-
56
- 1. Go to **[app.honcho.dev](https://app.honcho.dev)**
57
- 2. Sign up or log in
58
- 3. Copy your API key (starts with `hch-`)
59
-
60
- ### Step 2: Set Environment Variables
61
-
62
- **macOS / Linux** -- add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):
63
-
64
- ```bash
65
- # Required
66
- export HONCHO_API_KEY="hch-your-api-key-here"
67
-
68
- # Optional (defaults shown)
69
- export HONCHO_PEER_NAME="$USER" # Your name/identity
70
- export HONCHO_WORKSPACE="claude_code" # Workspace name
71
- ```
72
-
73
- Then reload your shell:
74
-
75
- ```bash
76
- source ~/.zshrc # or ~/.bashrc
77
- ```
78
-
79
- **Windows (PowerShell)** -- set a persistent user environment variable:
80
-
81
- ```powershell
82
- # Required
83
- [Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")
84
-
85
- # Optional
86
- [Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
87
- [Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")
88
- ```
89
-
90
- Then restart your terminal so the new variables take effect.
91
-
92
- ### Step 3: Install the Plugin
55
+ ### Step 1: Install the plugin
93
56
 
94
57
  ```
95
58
  /plugin marketplace add plastic-labs/claude-honcho
96
59
  /plugin install honcho@honcho
97
60
  ```
98
61
 
99
- ### Step 4: Restart Claude Code
62
+ Then run `/reload-plugins`, or restart Claude Code.
100
63
 
101
- ```bash
102
- # Exit Claude Code (ctrl+c or /exit)
103
- # Start it again -- you should see the Honcho pixel art and memory loading on startup.
104
- claude
105
- ```
64
+ ### Step 2: Connect Honcho
106
65
 
107
- ### Step 5: (Optional) Kick off your conversation with an interview
66
+ Click `○ honcho · set up` in the prompt footer, or run `/honcho setup`. Sign in with your browser, or paste an API key from [app.honcho.dev](https://app.honcho.dev). Your sign-in and key stay in the pane; they never go to Claude.
108
67
 
109
- ```
110
- /honcho:interview
111
- ```
68
+ ### Step 3: Start a new session
69
+
70
+ Run `/clear` or restart Claude Code. Memory loads at the start of each session, and `● honcho` in the footer opens the Honcho pane.
71
+
72
+ ### Step 4 (optional): Teach Honcho about you
112
73
 
113
- Claude will interview you about your personal preferences in order to kickstart a representation
114
- of you. What it learns will be saved in Honcho and remembered forever. The interview is specific
115
- to the peer name you chose in your environment: it will carry across different projects!
74
+ - `/honcho:interview` -- Claude asks about your preferences and saves what it learns. It carries across projects.
75
+ - `/honcho import` -- add your past Claude Code sessions to Honcho. Chats the plugin already saved are skipped.
116
76
 
117
77
  ## What You Get
118
78
 
119
79
  - **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
120
80
  - **Survives Context Wipes** — Even when Claude's context window resets, memory persists
121
- - **Git Awareness** — Detects branch switches, commits, and changes made outside Claude
122
- - **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
81
+ - **One session per chat** — Each Claude Code chat maps to its own Honcho session
123
82
  - **AI Self-Awareness** — Claude knows what it was working on, even after restarts
124
- - **Configurable Memory Injection** — Choose exactly what context is injected at session start and per turn
125
83
  - **Team Support** — Multiple people can share a workspace and build context together
126
- - **MCP Tools** — Search memory, query knowledge about you, and save insights
84
+ - **MCP Tools** — Search memory and ask Honcho about you, a project scope, or the whole workspace
127
85
 
128
86
  ## MCP Tools
129
87
 
@@ -131,268 +89,76 @@ The honcho plugin provides these tools via MCP:
131
89
 
132
90
  | Tool | Description |
133
91
  | -------------------- | -------------------------------------------------------------- |
134
- | `search` | Semantic search across session messages and saved conclusions |
135
- | `chat` | Query Honcho's knowledge about the user (dialectic reasoning) |
92
+ | `search` | Semantic search across messages (all sessions, or `scope: "session"` for this chat) and derived conclusions |
93
+ | `chat` | Ask Honcho about the user, optionally limited to a `scope`, or about the whole workspace (`workspace: true`) |
136
94
  | `create_conclusion` | Save insights about the user to memory |
137
- | `list_conclusions` | List saved conclusions |
138
- | `query_conclusions` | Semantic search over saved conclusions |
95
+ | `list_conclusions` | List derived conclusions (explicit ones are excluded) |
96
+ | `query_conclusions` | Semantic search over derived conclusions |
139
97
  | `delete_conclusion` | Delete a conclusion by ID |
140
- | `get_briefing` | Load the session briefing: session summary + peer card |
141
- | `get_context` | Retrieve the full context object (representation + peer card) |
142
- | `get_representation` | Retrieve the user's representation string |
143
98
  | `get_config` | View current configuration and status |
144
99
  | `set_config` | Change any configuration field programmatically |
145
- | `honcho_remember` | Fan-out dialectic recall (only registered when `rememberTool: true`) |
146
100
 
147
101
  ## Skills
148
102
 
149
103
  | Command | Description |
150
104
  | ------------------- | ----------------------------------------------------------- |
151
- | `/honcho:status` | Show current memory status and connection info |
152
- | `/honcho:config` | Interactive configuration menu |
153
- | `/honcho:setup` | First-time setup — validate API key and create config |
154
105
  | `/honcho:interview` | Interview to capture stable, cross-project user preferences |
155
- | `/honcho:briefing` | Load the session briefing via a visible tool call |
156
- | `/honcho:import` | Backfill past Claude Code sessions into Honcho memory |
157
106
  | `/honcho:insights` | Distill memory into CLAUDE.md edits, style rules, skill ideas |
107
+ | `/honcho` | Opens the Honcho pane. `/honcho setup` (sign in or enter an API key), `/honcho status`, `/honcho config`, `/honcho set <field> <value>` and `/honcho import` (backfill past sessions; `--yes` to upload) answer at once, without a Claude turn |
108
+
109
+ **Honcho pane.** Click `● honcho` in the prompt footer, or run `/honcho`, to open a pane beside the chat with a link to this chat's session in Honcho, your dream history and your peer card. Select a dream or the peer card to see it in full.
158
110
 
159
111
  ---
160
112
 
161
113
  ## Configuration
162
114
 
163
- All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use the `/honcho:config` skill, or use the `set_config` MCP tool. Environment variables work for initial setup but the config file takes precedence once it exists.
115
+ All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use `/honcho set <field> <value>`, or use the `set_config` MCP tool. Environment variables override the file.
164
116
 
165
117
  ### Config File Reference
166
118
 
167
119
  ```jsonc
168
120
  {
169
- // Required
170
- "apiKey": "hch-v2-...",
171
-
172
- // Identity
173
- "peerName": "alice", // Your name (default: $USER)
174
-
175
- // Host-specific settings — each tool gets its own workspace and AI peer
121
+ "schemaVersion": 2,
176
122
  "hosts": {
177
123
  "claude_code": {
178
- "workspace": "claude_code", // Workspace for Claude Code sessions
179
- "aiPeer": "claude", // AI identity in this workspace
180
- },
181
- "cursor": {
182
- "workspace": "cursor",
183
- "aiPeer": "cursor"
124
+ "oauth": { "accessToken": "…", "refreshToken": "…", "accessExpiresAt": 1794263473, "clientId": "claude-honcho", "scope": "write" },
125
+ "peerName": "alice", // asked during /honcho setup
126
+ "workspace": "claude_code",
127
+ "aiPeer": "claude"
184
128
  }
185
- },
186
-
187
- // Session mapping
188
- "sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance"
189
- "sessionPeerPrefix": true, // Prefix session names with peerName (default: true)
190
-
191
- // Message handling
192
- "saveMessages": true,
193
- "saveToolUse": false, // Save [Tool] action summaries (default: false)
194
- "saveGitEvents": false, // Save [Git External] state-change events (default: false)
195
- "messageUpload": {
196
- "maxUserTokens": null, // Truncate user messages (null = no limit)
197
- "maxAssistantTokens": null, // Truncate assistant messages (null = no limit)
198
- "summarizeAssistant": false // Summarize instead of sending full assistant text
199
- },
200
-
201
- // Context retrieval
202
- "contextRefresh": {
203
- "messageThreshold": 30, // Refresh context every N messages
204
- "ttlSeconds": 300, // Cache TTL for context
205
- "skipDialectic": false // Skip dialectic chat() calls in user-prompt hook
206
- },
207
- "reasoningLevel": "medium", // Default dialectic reasoning tier: "minimal" | "low" | "medium" | "high" | "max"
208
-
209
- // Memory injection (see "Memory Injection" below)
210
- "injection": {
211
- "sessionStart": ["directives", "summary", "peerCard"],
212
- "perTurn": ["userContext"]
213
- },
214
-
215
- // On-demand recall tool (see "The honcho_remember Tool" below)
216
- "rememberTool": false,
217
-
218
- // Observation mode
219
- "observationMode": "unified", // "unified" (default) | "directional"
220
-
221
- // Endpoint
222
- "endpoint": {
223
- "environment": "production" // "production" | "local"
224
- // or: "baseUrl": "http://your-server:8000/v3"
225
- },
226
-
227
- // Miscellaneous
228
- "redactPatterns": [], // Extra regexes redacted from tool summaries (additive to built-in secret patterns)
229
- "statusline": "on", // Memory statusline visibility: "on" | "off"
230
- "enabled": true,
231
- "logging": true,
232
-
233
- // Advanced: force all hosts to use the same workspace
234
- "globalOverride": false
235
- }
236
- ```
237
-
238
- ### Session Strategies
239
-
240
- Session strategy controls how Honcho maps your conversations to sessions. Change it with `/honcho:config` or `set_config`:
241
-
242
- | Strategy | Behavior | Best for |
243
- | --- | --- | --- |
244
- | `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory |
245
- | `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters |
246
- | `chat-instance` | Each Claude Code chat gets its own session. No continuity between restarts. | Ephemeral usage, experimentation, or when you want a clean slate each time |
247
-
248
- ### Memory Injection
249
-
250
- The `injection` config block controls exactly what memory is injected into Claude's context, on two surfaces: **once at session start** and **per prompt**. Each surface selects zero or more components; retrieval knobs shape what those components emit. Configure it with `/honcho:config` (memory injection settings), `set_config`, or by editing `~/.honcho/config.json`.
251
-
252
- **Session-start components** (default: `["directives", "summary", "peerCard"]`):
253
-
254
- | Component | What it injects |
255
- | --- | --- |
256
- | `directives` | Static memory-usage guidance — treat injected memory as background, use `chat`/`search` for recall, save insights with `create_conclusion` |
257
- | `summary` | The session's long summary narrative (skipped on a fresh session) |
258
- | `peerCard` | Your peer card — a structured identity/attribute list |
259
- | `peerRepresentation` | Your full derived representation, injected at full length |
260
- | `briefing` | A nudge for Claude to call the `get_briefing` MCP tool instead of injecting the summary and peer card inline — the tool call renders as an expandable row in the UI. Use it *in place of* `summary`/`peerCard`, not alongside them |
261
-
262
- **Per-turn components** (default: `["userContext"]`):
263
-
264
- | Component | What it injects |
265
- | --- | --- |
266
- | `userContext` | A fresh, prompt-scoped context fetch for *you* — conclusions selected by semantic search, shaped by the retrieval knobs below |
267
- | `assistantContext` | The same context fetch for the AI peer — what Honcho has derived about the assistant itself |
268
- | `sessionContext` | Recent raw messages from the currently mapped Honcho session, which can span other Claude instances sharing the session name |
269
- | `dialectic` | A reasoned `chat()` answer over your representation, seeded from `dialecticTemplate`. Off by default — much slower than a context fetch |
270
-
271
- **Retrieval knobs:**
272
-
273
- | Field | Default | Description |
274
- | --- | --- | --- |
275
- | `searchTopK` | `10` | Top-K conclusions pulled by the context fetch's semantic search |
276
- | `maxConclusions` | `15` | Max conclusions injected per context fetch |
277
- | `searchMaxDistance` | `0.6` | Max cosine distance for the semantic search — lower is stricter |
278
- | `searchQuerySource` | `"prompt"` | What drives the per-turn search: the raw `"prompt"` or extracted `"topics"` |
279
- | `sessionContextTokens` | `1500` | Token budget for the `sessionContext` message fetch |
280
- | `dialecticTemplate` | compact factual recall | Query template for the `dialectic` component; the prompt is substituted into `%{user_query}` |
281
- | `dialecticReasoning` | `"medium"` | Reasoning tier for the per-turn `dialectic` call — separate from the top-level `reasoningLevel` |
282
-
283
- If injected context feels off-topic, lower `searchMaxDistance`; if too sparse, raise it or bump `searchTopK`.
284
-
285
- **Visibility:** per-turn components report a one-line summary in the terminal by default. To print a component's full injected payload, list it in `showContents`:
286
-
287
- ```json
288
- { "injection": { "showContents": ["userContext", "sessionContext"] } }
289
- ```
290
-
291
- ### The `honcho_remember` Tool
292
-
293
- An experimental on-demand recall tool. When enabled, Claude gets a `honcho_remember` MCP tool that fans out up to 5 parallel dialectic queries about you and returns per-question answers — useful before starting a task, when catching up ("where were we?"), or whenever your history could shape the response.
294
-
295
- To enable it, just ask Claude: *"Set my Honcho rememberTool config to true"* (it uses the `set_config` tool). Or set it in `~/.honcho/config.json`:
296
-
297
- ```json
298
- {
299
- "hosts": {
300
- "claude_code": { "rememberTool": true }
301
129
  }
302
130
  }
303
131
  ```
304
132
 
305
- Then restart Claude Code — MCP tools register at startup.
306
-
307
- When it's on, the injected session-start directives steer Claude to use it proactively as the primary recall path.
308
-
309
- ### Observation Mode
133
+ `/honcho setup` writes one of two credentials:
310
134
 
311
- Controls how Honcho stores and retrieves conclusions about you. Change it via `set_config` or edit `config.json` directly. Requires a Claude Code restart.
135
+ - `oauth`: "Sign in with your browser". Your Claude Code sign-in to Honcho cloud, refreshed automatically. Other Honcho plugins keep their own.
136
+ - `apiKey`: "Use an API key", for a key from app.honcho.dev or a self-hosted Honcho (`"baseUrl": "http://localhost:8000"`; browser sign-in is cloud-only).
312
137
 
313
- | Mode | Behavior | Best for |
314
- | --- | --- | --- |
315
- | `unified` (default) | All agents write to your self-observation collection (`observer=you, observed=you`). Conclusions are portable — switch between Claude, Hermes, or any agent without losing memory. | Most users, when you want to build a unified context hub, agent-switching |
316
- | `directional` | Each AI peer keeps its own separate view of you (`observer=aiPeer, observed=you`). Claude's observations stay with Claude, Hermes' with Hermes. | Multi-peer workspaces where you want isolated per-peer(agent) representations |
138
+ `HONCHO_API_KEY` overrides both.
317
139
 
318
- > **Peer defaults:** The plugin does not explicitly set `observeMe` or `observeOthers` on peers — it uses the server-side defaults. If you want to change how a peer observes (e.g., disable self-observation), update the peer's defaults via API or on [app.honcho.dev](https://app.honcho.dev). The only override the plugin applies is `observeOthers: true` on the AI peer in `directional` mode.
140
+ Each plugin keeps its settings in its own block under `hosts`; nothing at the top level is read. If your file still has top-level settings or old key names, the plugin copies them into `hosts.claude_code` at session start and says so once, and leaves the top level and other plugins' blocks as they are. Logs go to `~/.honcho/activity.log`. To turn the plugin off, disable it in Claude Code's `/plugin` menu.
319
141
 
320
- To change:
142
+ ### Sessions
321
143
 
322
- - Ask Claude: *"Set my observation mode to directional"*
323
- - Or edit `~/.honcho/config.json`:
324
- ```json
325
- { "observationMode": "directional" }
326
- ```
327
- - Or per-host:
328
- ```json
329
- {
330
- "hosts": {
331
- "claude_code": { "observationMode": "directional" }
332
- }
333
- }
334
- ```
144
+ Each Claude Code chat maps to one Honcho session whose id is the Claude Code session id. Resuming a chat continues its session; `/clear` and new chats start a new one. Memory about you still carries across every chat in the workspace.
335
145
 
336
- > **Note:** Switching modes doesn't automatically migrate existing conclusions. Each mode reads from a different collection. See [Migrating Observations](#migrating-observations) below to move conclusions between collections.
146
+ New sessions also join two Honcho scopes: one named after the git repository (worktrees share the main repo's name; outside git, the directory name) and one named after the machine's hostname. Use them to query memory from just one project or one machine.
337
147
 
338
- ### Migrating Observations
339
-
340
- When switching observation modes, conclusions stored under the old mode's collection won't be visible to the new mode. Use the migration script to copy them over:
341
-
342
- ```bash
343
- # Requires: pip install honcho-ai
344
- # Set your API key: export HONCHO_API_KEY="hch-..."
345
-
346
- # Dry run — see what would be migrated (directional → unified)
347
- python scripts/migrate-observations.py \
348
- --workspace agents \
349
- --from-observer claude \
350
- --user ajspig \
351
- --dry-run
352
-
353
- # Execute the migration
354
- python scripts/migrate-observations.py \
355
- --workspace agents \
356
- --from-observer claude \
357
- --user ajspig
358
-
359
- # Execute and delete the source conclusions after migration
360
- python scripts/migrate-observations.py \
361
- --workspace agents \
362
- --from-observer claude \
363
- --user ajspig \
364
- --delete-source
365
- ```
148
+ This mapping isn't configurable. If you want a different session layout, connect to Honcho through the [Honcho MCP server](https://mcp.honcho.dev) and manage sessions yourself.
366
149
 
367
- The script:
368
- - Reads all conclusions from the source collection (e.g., `observer=claude, observed=ajspig`)
369
- - Deduplicates by content against the destination (e.g., `observer=ajspig, observed=ajspig`)
370
- - Creates only the conclusions that don't already exist in the destination
371
- - Handles rate limiting with automatic retries
372
-
373
- To migrate in the other direction (unified → directional):
374
-
375
- ```bash
376
- python scripts/migrate-observations.py \
377
- --workspace agents \
378
- --from-observer ajspig \
379
- --to-observer claude \
380
- --user ajspig
381
- ```
382
-
383
- If you use multiple AI agents, run the script once per agent:
150
+ ### Memory Injection
384
151
 
385
- ```bash
386
- # Migrate Claude's observations to unified
387
- python scripts/migrate-observations.py -w agents --from-observer claude --user ajspig
152
+ At session start the plugin injects two things:
388
153
 
389
- # Migrate Hermes' observations to unified
390
- python scripts/migrate-observations.py -w agents --from-observer hermes --user ajspig
391
- ```
154
+ - **Directives**: how to use Honcho memory. Treat it as background, recall with the `chat` tool (naming this chat's repo and machine scopes), and save insights with `create_conclusion`.
155
+ - **Your peer card**: a structured identity/attribute list.
392
156
 
393
- Run with `--help` for all options.
157
+ Nothing is injected per prompt, and nothing is fetched with `context()`. Tools that read conclusions (`search`, `list_conclusions`, `query_conclusions`) return only derived conclusions; explicit ones are filtered out. Claude recalls memory when it needs it by calling `chat`:
394
158
 
395
- Session names are prefixed with your `peerName` by default (e.g., `alice-my-project`). Set `sessionPeerPrefix: false` if you're the only user and want shorter names.
159
+ - **About you** (default): an answer from everything Honcho knows about you.
160
+ - **Within a scope**: pass `scope` (e.g. the repo name) to answer only from that scope's sessions.
161
+ - **Across the workspace**: pass `workspace: true` to ask about every peer in the workspace.
396
162
 
397
163
  ### Host-Aware Configuration
398
164
 
@@ -404,34 +170,17 @@ The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and
404
170
  3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
405
171
  4. Default: `claude_code`
406
172
 
407
- ### Global Override
408
-
409
- If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field:
410
-
411
- ```jsonc
412
- {
413
- "globalOverride": true,
414
- "workspace": "shared",
415
- "hosts": {
416
- "claude_code": { "aiPeer": "claude" },
417
- "cursor": { "aiPeer": "cursor" }
418
- }
419
- }
420
- ```
421
-
422
- All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name.
423
-
424
173
  ### Team Setup with Shared Context
425
174
 
426
- Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity, and sessions are automatically prefixed with it to avoid collisions.
175
+ Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity.
427
176
 
428
177
  **Person A** (`~/.honcho/config.json`):
429
178
  ```json
430
179
  {
431
- "apiKey": "hch-v2-team-key...",
432
- "peerName": "alice",
433
180
  "hosts": {
434
181
  "claude_code": {
182
+ "apiKey": "hch-v2-team-key...",
183
+ "peerName": "alice",
435
184
  "workspace": "team-acme",
436
185
  "aiPeer": "claude"
437
186
  }
@@ -442,10 +191,10 @@ Multiple people can share context by pointing to the same workspace. Each person
442
191
  **Person B** (`~/.honcho/config.json`):
443
192
  ```json
444
193
  {
445
- "apiKey": "hch-v2-team-key...",
446
- "peerName": "bob",
447
194
  "hosts": {
448
195
  "claude_code": {
196
+ "apiKey": "hch-v2-team-key...",
197
+ "peerName": "bob",
449
198
  "workspace": "team-acme",
450
199
  "aiPeer": "claude"
451
200
  }
@@ -453,23 +202,20 @@ Multiple people can share context by pointing to the same workspace. Each person
453
202
  }
454
203
  ```
455
204
 
456
- Both Alice and Bob write to the `team-acme` workspace. Their sessions are namespaced (e.g., `alice-my-project`, `bob-my-project`) so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users. If you want fully independent sessions, set `sessionPeerPrefix: false` — but this is not recommended in shared workspaces.
205
+ Both Alice and Bob write to the `team-acme` workspace. Each chat has its own session, so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users.
457
206
 
458
207
  ### Environment Variables
459
208
 
460
- Environment variables work for initial bootstrap (before a config file exists). Once `~/.honcho/config.json` is written, the config file takes precedence for host-specific fields like `workspace`.
209
+ Environment variables override `hosts.claude_code` in `~/.honcho/config.json`.
461
210
 
462
211
  | Variable | Required | Default | Description |
463
212
  | ---------------------- | -------- | ------------- | ----------------------------------------------------------------- |
464
213
  | `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) |
465
214
  | `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system |
466
- | `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) |
467
- | `HONCHO_AI_PEER` | No | `claude` | AI peer name |
215
+ | `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name |
216
+ | `HONCHO_AI_PEER` | No | `claude` | AI peer name (the old `HONCHO_CLAUDE_PEER` still works in an env-only setup) |
468
217
  | `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` |
469
- | `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL |
470
- | `HONCHO_ENABLED` | No | `true` | Set to `false` to disable |
471
- | `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages |
472
- | `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |
218
+ | `HONCHO_BASE_URL` | No | Honcho cloud | Honcho API URL (the old `HONCHO_ENDPOINT` still works in an env-only setup, with no key or sign-in in the config file) |
473
219
 
474
220
  ## How It Works
475
221
 
@@ -477,29 +223,27 @@ Environment variables work for initial bootstrap (before a config file exists).
477
223
  ┌─────────────────────────────────────────────────────────────────┐
478
224
  │ Claude Code │
479
225
  ├─────────────────────────────────────────────────────────────────┤
480
- │ SessionStart │ UserPrompt │ PostToolUse │ SessionEnd │
226
+ │ SessionStart │ UserPrompt │ Stop │ SessionEnd │
481
227
  │ ─────────── │ ─────────── │ ──────────── │ ────────── │
482
- │ Load context │ Save message │ Log activity │ Upload all │
483
- │ from Honcho │ to Honcho │ to Honcho │ + summary │
228
+ │ Load peer card │ Save message │ Save Claude's │ Clean up │
229
+ │ + directives │ to Honcho │ reply │ │
484
230
  └─────────────────────────────────────────────────────────────────┘
485
231
  │
486
232
  ▼
487
233
  ┌─────────────────────────────────────────────────────────────────┐
488
234
  │ Honcho API │
489
235
  │ │
490
- │ Your messages and Claude's work → Persistent Memory → │
491
- │ Retrieved as context at session start │
236
+ │ Your messages and Claude's replies → Persistent Memory → │
237
+ │ Recalled on demand through the chat tool │
492
238
  └─────────────────────────────────────────────────────────────────┘
493
239
  ```
494
240
 
495
241
  The plugin hooks into Claude Code's lifecycle events:
496
242
 
497
- - **SessionStart**: Loads your context and history from Honcho
498
- - **UserPrompt**: Saves your messages and retrieves relevant context
499
- - **PostToolUse**: Logs Claude's actions (file edits, commands, etc.)
500
- - **PreCompact**: Anchors a memory snapshot before context compaction so knowledge survives summarization
501
- - **Stop**: Flushes any pending messages
502
- - **SessionEnd**: Uploads remaining messages and generates a summary
243
+ - **SessionStart**: Joins this chat's session to its repo and machine scopes, and injects the memory directives and your peer card
244
+ - **UserPrompt**: Saves your messages (nothing is retrieved per turn; Claude calls `chat` when it needs memory)
245
+ - **Stop**: Saves Claude's replies
246
+ - **SessionEnd**: Clears local per-chat state
503
247
 
504
248
  ## Troubleshooting
505
249
 
@@ -512,7 +256,7 @@ The plugin hooks into Claude Code's lifecycle events:
512
256
  echo $env:HONCHO_API_KEY # Windows PowerShell
513
257
  ```
514
258
 
515
- If empty, set it (see Step 2 in Quick Start) and restart your terminal.
259
+ If empty, run `/honcho setup`, or set it (see the environment-variable setup near the end) and restart your terminal.
516
260
 
517
261
  2. **Check the plugin is installed:**
518
262
 
@@ -524,33 +268,23 @@ The plugin hooks into Claude Code's lifecycle events:
524
268
 
525
269
  3. **Restart Claude Code** after making changes.
526
270
 
527
- 4. **Run `/honcho:status`** to see connection state, workspace, and session info.
528
-
529
- ### Memory not persisting between sessions
530
-
531
- Make sure `saveMessages` is not set to `false` in your config (or `HONCHO_SAVE_MESSAGES` in env).
271
+ 4. **Run `/honcho status`** to see connection state, workspace, and session info.
532
272
 
533
273
  ### Using a local Honcho instance
534
274
 
535
275
  Via config file:
536
276
  ```json
537
- { "endpoint": { "environment": "local" } }
277
+ { "hosts": { "claude_code": { "baseUrl": "http://localhost:8000" } } }
538
278
  ```
539
279
 
540
280
  Or via env var:
541
281
  ```bash
542
- export HONCHO_ENDPOINT="local" # Uses localhost:8000
543
- # or
544
- export HONCHO_ENDPOINT="http://your-server:8000/v3"
282
+ export HONCHO_BASE_URL="http://localhost:8000"
545
283
  ```
546
284
 
547
285
  ### Temporarily disabling memory
548
286
 
549
- ```bash
550
- export HONCHO_ENABLED="false"
551
- ```
552
-
553
- Or set `"enabled": false` in your config file. Restart Claude Code to take effect.
287
+ Disable the plugin in Claude Code's `/plugin` menu, and enable it again when you're done.
554
288
 
555
289
  ---
556
290
 
@@ -586,6 +320,48 @@ This plugin provides skills to help you integrate Honcho into your projects and
586
320
 
587
321
  Then remove the environment variables from your shell config if desired.
588
322
 
323
+ <details>
324
+ <summary>Claude Code before v2.1.287: set up with environment variables</summary>
325
+
326
+ Older Claude Code versions don't load the plugin's mod, so there is no `/honcho` command or Honcho pane. Memory still works once a key is set.
327
+
328
+ 1. Get an API key (starts with `hch-`) at [app.honcho.dev](https://app.honcho.dev).
329
+ 2. Set it in your environment.
330
+
331
+ **macOS / Linux** -- add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):
332
+
333
+ ```bash
334
+ # Required
335
+ export HONCHO_API_KEY="hch-your-api-key-here"
336
+
337
+ # Optional (defaults shown)
338
+ export HONCHO_PEER_NAME="$USER" # Your name/identity
339
+ export HONCHO_WORKSPACE="claude_code" # Workspace name
340
+ ```
341
+
342
+ Then reload your shell:
343
+
344
+ ```bash
345
+ source ~/.zshrc # or ~/.bashrc
346
+ ```
347
+
348
+ **Windows (PowerShell)** -- set a persistent user environment variable:
349
+
350
+ ```powershell
351
+ # Required
352
+ [Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")
353
+
354
+ # Optional
355
+ [Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
356
+ [Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")
357
+ ```
358
+
359
+ Then restart your terminal so the new variables take effect.
360
+
361
+ 3. Install the plugin (Step 1 above) and restart Claude Code.
362
+
363
+ </details>
364
+
589
365
  ---
590
366
 
591
367
  ## License