ScuttleBot
docs: remove internal Claude session path references from public docs
Commit
c61f88f4bbd59f79c7411b1cce914463b95d740465379e31172f727705b336f7
Parent
10b6d9298a01246…
3 files changed
+1
-1
+1
-1
+4
-4
+1
-1
| --- README.md | ||
| +++ README.md | ||
| @@ -106,11 +106,11 @@ | ||
| 106 | 106 | |
| 107 | 107 | - **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen. |
| 108 | 108 | - **Human-in-the-loop control.** Mention the session nick in IRC and the broker injects your message directly into the live terminal — with a Ctrl+C interrupt if the agent is mid-task. |
| 109 | 109 | - **PTY wrapper.** The relay uses a real pseudo-terminal, so the agent behaves exactly as it would in an interactive terminal. Readline, color output, and interactive prompts all work. |
| 110 | 110 | - **Two transport modes.** Use the HTTP bridge (simpler setup) or a full IRC socket (richer presence, multi-channel). In IRC mode, each session appears as its own named user in the channel. |
| 111 | -- **Session discovery.** The broker watches the agent's native session format (e.g. Claude Code's `~/.claude/projects/*/session.jsonl`) and mirrors structured output without requiring any changes to the agent itself. | |
| 111 | +- **Session discovery.** The broker watches the agent's native session log format and mirrors structured output without requiring any changes to the agent itself. | |
| 112 | 112 | - **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel. |
| 113 | 113 | |
| 114 | 114 | Relay runtime primers: |
| 115 | 115 | |
| 116 | 116 | - [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill |
| 117 | 117 |
| --- README.md | |
| +++ README.md | |
| @@ -106,11 +106,11 @@ | |
| 106 | |
| 107 | - **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen. |
| 108 | - **Human-in-the-loop control.** Mention the session nick in IRC and the broker injects your message directly into the live terminal — with a Ctrl+C interrupt if the agent is mid-task. |
| 109 | - **PTY wrapper.** The relay uses a real pseudo-terminal, so the agent behaves exactly as it would in an interactive terminal. Readline, color output, and interactive prompts all work. |
| 110 | - **Two transport modes.** Use the HTTP bridge (simpler setup) or a full IRC socket (richer presence, multi-channel). In IRC mode, each session appears as its own named user in the channel. |
| 111 | - **Session discovery.** The broker watches the agent's native session format (e.g. Claude Code's `~/.claude/projects/*/session.jsonl`) and mirrors structured output without requiring any changes to the agent itself. |
| 112 | - **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel. |
| 113 | |
| 114 | Relay runtime primers: |
| 115 | |
| 116 | - [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill |
| 117 |
| --- README.md | |
| +++ README.md | |
| @@ -106,11 +106,11 @@ | |
| 106 | |
| 107 | - **Real-time observability.** Tool calls, file edits, bash commands, and assistant replies are all mirrored to IRC as they happen. |
| 108 | - **Human-in-the-loop control.** Mention the session nick in IRC and the broker injects your message directly into the live terminal — with a Ctrl+C interrupt if the agent is mid-task. |
| 109 | - **PTY wrapper.** The relay uses a real pseudo-terminal, so the agent behaves exactly as it would in an interactive terminal. Readline, color output, and interactive prompts all work. |
| 110 | - **Two transport modes.** Use the HTTP bridge (simpler setup) or a full IRC socket (richer presence, multi-channel). In IRC mode, each session appears as its own named user in the channel. |
| 111 | - **Session discovery.** The broker watches the agent's native session log format and mirrors structured output without requiring any changes to the agent itself. |
| 112 | - **Secret sanitization.** Bearer tokens, API keys, and hex secrets are stripped before anything reaches the channel. |
| 113 | |
| 114 | Relay runtime primers: |
| 115 | |
| 116 | - [`skills/scuttlebot-relay/`](skills/scuttlebot-relay/) — shared install/config skill |
| 117 |
+1
-1
| --- docs/guide/adding-agents.md | ||
| +++ docs/guide/adding-agents.md | ||
| @@ -283,11 +283,11 @@ | ||
| 283 | 283 | |
| 284 | 284 | Each runtime stores its session data in a different location: |
| 285 | 285 | |
| 286 | 286 | | Runtime | Session log location | |
| 287 | 287 | |---------|---------------------| |
| 288 | -| Claude Code | `~/.claude/projects/{cwd-hash}/` — JSONL files named by session UUID | | |
| 288 | +| Claude Code | Claude projects directory — JSONL files named by session UUID | | |
| 289 | 289 | | Codex | `~/.codex/sessions/{session-id}.jsonl` | |
| 290 | 290 | | Gemini CLI | `~/.gemini/sessions/{session-id}.jsonl` | |
| 291 | 291 | |
| 292 | 292 | To find the latest session file: |
| 293 | 293 | |
| 294 | 294 |
| --- docs/guide/adding-agents.md | |
| +++ docs/guide/adding-agents.md | |
| @@ -283,11 +283,11 @@ | |
| 283 | |
| 284 | Each runtime stores its session data in a different location: |
| 285 | |
| 286 | | Runtime | Session log location | |
| 287 | |---------|---------------------| |
| 288 | | Claude Code | `~/.claude/projects/{cwd-hash}/` — JSONL files named by session UUID | |
| 289 | | Codex | `~/.codex/sessions/{session-id}.jsonl` | |
| 290 | | Gemini CLI | `~/.gemini/sessions/{session-id}.jsonl` | |
| 291 | |
| 292 | To find the latest session file: |
| 293 | |
| 294 |
| --- docs/guide/adding-agents.md | |
| +++ docs/guide/adding-agents.md | |
| @@ -283,11 +283,11 @@ | |
| 283 | |
| 284 | Each runtime stores its session data in a different location: |
| 285 | |
| 286 | | Runtime | Session log location | |
| 287 | |---------|---------------------| |
| 288 | | Claude Code | Claude projects directory — JSONL files named by session UUID | |
| 289 | | Codex | `~/.codex/sessions/{session-id}.jsonl` | |
| 290 | | Gemini CLI | `~/.gemini/sessions/{session-id}.jsonl` | |
| 291 | |
| 292 | To find the latest session file: |
| 293 | |
| 294 |
+4
-4
| --- docs/guide/relays.md | ||
| +++ docs/guide/relays.md | ||
| @@ -90,13 +90,13 @@ | ||
| 90 | 90 | |
| 91 | 91 | === "Claude" |
| 92 | 92 | |
| 93 | 93 | **Binary:** `cmd/claude-relay` |
| 94 | 94 | **Default transport:** IRC |
| 95 | - **Session file:** `~/.claude/projects/<sanitized-cwd>/<session>.jsonl` | |
| 95 | + **Session file:** Claude Code session JSONL (written to the Claude projects directory) | |
| 96 | 96 | |
| 97 | - Claude Code writes a JSONL file for each session under `~/.claude/projects/`. The relay discovers the matching file by scanning for `.jsonl` files modified after session start, verifying the `cwd` field in the first few entries. It then tails from the current end of file so only new output is mirrored. | |
| 97 | + Claude Code writes a JSONL file for each session. The relay discovers the matching file by scanning for `.jsonl` files modified after session start, verifying the `cwd` field in the first few entries. It then tails from the current end of file so only new output is mirrored. | |
| 98 | 98 | |
| 99 | 99 | Mirrored entry types: |
| 100 | 100 | |
| 101 | 101 | | JSONL block type | What gets posted | |
| 102 | 102 | |---|---| |
| @@ -136,11 +136,11 @@ | ||
| 136 | 136 | |
| 137 | 137 | ## Session mirroring in detail |
| 138 | 138 | |
| 139 | 139 | The broker finds the session file by: |
| 140 | 140 | |
| 141 | -1. computing `~/.claude/projects/<sanitized-cwd>/` (Claude) or the runtime equivalent | |
| 141 | +1. locating the runtime's session directory (Claude projects dir, Codex sessions dir, etc.) | |
| 142 | 142 | 2. scanning for `.jsonl` files modified after `startedAt - 2s` |
| 143 | 143 | 3. peeking at the first five lines of each candidate to match `cwd` against the working directory |
| 144 | 144 | 4. selecting the newest match |
| 145 | 145 | 5. seeking to the end of the file and entering a tail loop (250ms poll interval) |
| 146 | 146 | |
| @@ -363,11 +363,11 @@ | ||
| 363 | 363 | ``` |
| 364 | 364 | |
| 365 | 365 | The broker waited 20 seconds for a matching session JSONL file and gave up. This happens when: |
| 366 | 366 | |
| 367 | 367 | - Claude Code is run with `--help`, `--version`, or a command that doesn't start a real session (`help`, `completion`). The relay does not mirror these — this is expected behaviour. |
| 368 | -- The `~/.claude/projects/` directory path does not match the working directory. Verify with `pwd` and check that `~/.claude/projects/` contains a directory named after your sanitized path. | |
| 368 | +- The Claude projects directory does not contain a session matching the working directory. Verify with `pwd` and check that Claude Code has written a session file for the current path. | |
| 369 | 369 | - The session file is being written to a different directory (non-default Claude config). Set `CLAUDE_HOME` or `XDG_CONFIG_HOME` consistently. |
| 370 | 370 | |
| 371 | 371 | ### Messages not being injected |
| 372 | 372 | |
| 373 | 373 | Check that your IRC message actually mentions the session nick with a word boundary. The relay uses a strict word-boundary match. `hello claude-myrepo-a1b2c3d4` works. `hello claude-myrepo-a1b2c3d4!` does not (trailing `!`). Address with a colon or comma: |
| 374 | 374 |
| --- docs/guide/relays.md | |
| +++ docs/guide/relays.md | |
| @@ -90,13 +90,13 @@ | |
| 90 | |
| 91 | === "Claude" |
| 92 | |
| 93 | **Binary:** `cmd/claude-relay` |
| 94 | **Default transport:** IRC |
| 95 | **Session file:** `~/.claude/projects/<sanitized-cwd>/<session>.jsonl` |
| 96 | |
| 97 | Claude Code writes a JSONL file for each session under `~/.claude/projects/`. The relay discovers the matching file by scanning for `.jsonl` files modified after session start, verifying the `cwd` field in the first few entries. It then tails from the current end of file so only new output is mirrored. |
| 98 | |
| 99 | Mirrored entry types: |
| 100 | |
| 101 | | JSONL block type | What gets posted | |
| 102 | |---|---| |
| @@ -136,11 +136,11 @@ | |
| 136 | |
| 137 | ## Session mirroring in detail |
| 138 | |
| 139 | The broker finds the session file by: |
| 140 | |
| 141 | 1. computing `~/.claude/projects/<sanitized-cwd>/` (Claude) or the runtime equivalent |
| 142 | 2. scanning for `.jsonl` files modified after `startedAt - 2s` |
| 143 | 3. peeking at the first five lines of each candidate to match `cwd` against the working directory |
| 144 | 4. selecting the newest match |
| 145 | 5. seeking to the end of the file and entering a tail loop (250ms poll interval) |
| 146 | |
| @@ -363,11 +363,11 @@ | |
| 363 | ``` |
| 364 | |
| 365 | The broker waited 20 seconds for a matching session JSONL file and gave up. This happens when: |
| 366 | |
| 367 | - Claude Code is run with `--help`, `--version`, or a command that doesn't start a real session (`help`, `completion`). The relay does not mirror these — this is expected behaviour. |
| 368 | - The `~/.claude/projects/` directory path does not match the working directory. Verify with `pwd` and check that `~/.claude/projects/` contains a directory named after your sanitized path. |
| 369 | - The session file is being written to a different directory (non-default Claude config). Set `CLAUDE_HOME` or `XDG_CONFIG_HOME` consistently. |
| 370 | |
| 371 | ### Messages not being injected |
| 372 | |
| 373 | Check that your IRC message actually mentions the session nick with a word boundary. The relay uses a strict word-boundary match. `hello claude-myrepo-a1b2c3d4` works. `hello claude-myrepo-a1b2c3d4!` does not (trailing `!`). Address with a colon or comma: |
| 374 |
| --- docs/guide/relays.md | |
| +++ docs/guide/relays.md | |
| @@ -90,13 +90,13 @@ | |
| 90 | |
| 91 | === "Claude" |
| 92 | |
| 93 | **Binary:** `cmd/claude-relay` |
| 94 | **Default transport:** IRC |
| 95 | **Session file:** Claude Code session JSONL (written to the Claude projects directory) |
| 96 | |
| 97 | Claude Code writes a JSONL file for each session. The relay discovers the matching file by scanning for `.jsonl` files modified after session start, verifying the `cwd` field in the first few entries. It then tails from the current end of file so only new output is mirrored. |
| 98 | |
| 99 | Mirrored entry types: |
| 100 | |
| 101 | | JSONL block type | What gets posted | |
| 102 | |---|---| |
| @@ -136,11 +136,11 @@ | |
| 136 | |
| 137 | ## Session mirroring in detail |
| 138 | |
| 139 | The broker finds the session file by: |
| 140 | |
| 141 | 1. locating the runtime's session directory (Claude projects dir, Codex sessions dir, etc.) |
| 142 | 2. scanning for `.jsonl` files modified after `startedAt - 2s` |
| 143 | 3. peeking at the first five lines of each candidate to match `cwd` against the working directory |
| 144 | 4. selecting the newest match |
| 145 | 5. seeking to the end of the file and entering a tail loop (250ms poll interval) |
| 146 | |
| @@ -363,11 +363,11 @@ | |
| 363 | ``` |
| 364 | |
| 365 | The broker waited 20 seconds for a matching session JSONL file and gave up. This happens when: |
| 366 | |
| 367 | - Claude Code is run with `--help`, `--version`, or a command that doesn't start a real session (`help`, `completion`). The relay does not mirror these — this is expected behaviour. |
| 368 | - The Claude projects directory does not contain a session matching the working directory. Verify with `pwd` and check that Claude Code has written a session file for the current path. |
| 369 | - The session file is being written to a different directory (non-default Claude config). Set `CLAUDE_HOME` or `XDG_CONFIG_HOME` consistently. |
| 370 | |
| 371 | ### Messages not being injected |
| 372 | |
| 373 | Check that your IRC message actually mentions the session nick with a word boundary. The relay uses a strict word-boundary match. `hello claude-myrepo-a1b2c3d4` works. `hello claude-myrepo-a1b2c3d4!` does not (trailing `!`). Address with a colon or comma: |
| 374 |