@threadbase-sh/streamer 1.22.1 → 1.23.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 +79 -116
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,41 +1,31 @@
|
|
|
1
1
|
# @threadbase-sh/streamer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Runs and manages Claude Code sessions on a server: spawns them in a PTY, streams terminal output over WebSocket, and exposes a REST API for conversation history, search, and session control.
|
|
4
4
|
|
|
5
5
|
## Quick Start
|
|
6
6
|
|
|
7
|
-
###
|
|
7
|
+
### npm (recommended)
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
npm install -g @threadbase-sh/streamer
|
|
11
|
-
|
|
12
|
-
# One-time setup:
|
|
13
|
-
tb-streamer set-key <YOUR_API_KEY>
|
|
14
|
-
|
|
15
|
-
# Start the server:
|
|
11
|
+
tb-streamer set-key <YOUR_API_KEY> # one-time setup
|
|
16
12
|
tb-streamer serve
|
|
17
13
|
```
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
Only `node-pty` compiles on install; everything else ships prebuilt.
|
|
20
16
|
|
|
21
|
-
###
|
|
17
|
+
### Homebrew (macOS + Linux)
|
|
22
18
|
|
|
23
19
|
```bash
|
|
24
20
|
brew tap RonenMars/threadbase
|
|
25
21
|
brew install tb-streamer
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
tb-streamer set-key <YOUR_API_KEY>
|
|
29
|
-
|
|
30
|
-
# Start the service (also starts on login):
|
|
31
|
-
brew services start tb-streamer
|
|
22
|
+
tb-streamer set-key <YOUR_API_KEY> # one-time setup
|
|
23
|
+
brew services start tb-streamer # also starts on login
|
|
32
24
|
```
|
|
33
25
|
|
|
34
|
-
|
|
26
|
+
Stop/restart with `brew services stop|restart tb-streamer`. Mutually exclusive with the manual `scripts/deploy.sh` install — if switching from that, run `launchctl bootout gui/$UID/com.threadbase.streamer` first.
|
|
35
27
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
### Run from source
|
|
28
|
+
### Build locally
|
|
39
29
|
|
|
40
30
|
```bash
|
|
41
31
|
npm install
|
|
@@ -43,126 +33,99 @@ npm run build
|
|
|
43
33
|
node dist/cli.cjs serve --verbose --local-no-auth
|
|
44
34
|
```
|
|
45
35
|
|
|
46
|
-
|
|
36
|
+
#### Server address
|
|
47
37
|
|
|
48
|
-
|
|
38
|
+
The server listens on `http://localhost:8766` (WebSocket at `ws://localhost:8766/ws`).
|
|
49
39
|
|
|
50
|
-
|
|
40
|
+
#### Automatic updates
|
|
51
41
|
|
|
52
|
-
|
|
42
|
+
npm and Homebrew installs can auto-update: [docs/guides/auto-update.md](docs/guides/auto-update.md).
|
|
53
43
|
|
|
54
|
-
##
|
|
44
|
+
## Remote Access
|
|
55
45
|
|
|
56
|
-
|
|
46
|
+
The server only binds to `127.0.0.1:8766` by default. To let the mobile app reach it from outside your LAN, expose it via a tunnel — the fastest is a Cloudflare quick-tunnel (no account needed):
|
|
57
47
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
- A chokidar-backed watcher tails conversation JSONL files into the SQLite cache, which backs the conversation/list endpoints without filesystem scans.
|
|
63
|
-
- When the last WebSocket subscriber disconnects, a grace timer (default 4.5 minutes) puts the PTY on hold — history intact, resumable any time.
|
|
64
|
-
|
|
65
|
-
Full runtime flow and module reference: [docs/how-it-works.md](docs/how-it-works.md). Dated design documents: [docs/architecture/](docs/architecture/README.md).
|
|
66
|
-
|
|
67
|
-
## Relationship to Claude Code dynamic workflows
|
|
68
|
-
|
|
69
|
-
[Claude Code dynamic workflows](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code) live *inside* a Claude Code session — the kind of session **PTY mode** hosts. The meaningful comparison is with **`--multi-agent-flow` mode**, where the streamer hands each turn off to a Temporal pipeline in `tb-multi-agent` instead of a `node-pty` Claude session: developer-triggered in-session orchestration vs. durable per-turn orchestration with webhook → WebSocket result delivery.
|
|
48
|
+
```bash
|
|
49
|
+
bash scripts/remote-access/cloudflare.sh # macOS/Linux/WSL/Git Bash
|
|
50
|
+
pwsh scripts/remote-access/cloudflare.ps1 # anywhere pwsh is installed
|
|
51
|
+
```
|
|
70
52
|
|
|
71
|
-
|
|
53
|
+
Other providers and full setup: [docs/guides/remote-access](docs/guides/remote-access/README.md).
|
|
72
54
|
|
|
73
|
-
##
|
|
55
|
+
## Development
|
|
74
56
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
| POST | `/api/sessions/resume` | Resume a conversation (creates managed session) |
|
|
84
|
-
| POST | `/api/sessions/:id/input` | Send input to a managed session |
|
|
85
|
-
| POST | `/api/sessions/:id/cancel` | Cancel a managed session |
|
|
86
|
-
| GET | `/api/sessions/:id/output` | Get terminal output buffer |
|
|
87
|
-
| POST | `/api/sessions/:id/files` | Upload a file attachment to a session |
|
|
88
|
-
| GET | `/api/conversations` | Paginated conversation history |
|
|
89
|
-
| GET | `/api/conversations/count` | Count conversations matching optional filters |
|
|
90
|
-
| GET | `/api/conversations/:id` | Full conversation with messages |
|
|
91
|
-
| GET | `/project-chats` | Unified active-sessions + historical-conversations list (discriminated union); accepts `?refreshConversations=1` |
|
|
92
|
-
| GET | `/api/search?q=...` | Full-text search across conversations |
|
|
93
|
-
| GET | `/api/browse` | Browse the file system |
|
|
94
|
-
| POST | `/api/browse/mkdir` | Create a directory |
|
|
95
|
-
| GET | `/api/profiles` | List scan profiles |
|
|
96
|
-
| POST | `/api/push/register` | Register a push notification token |
|
|
97
|
-
| POST | `/api/pair/start` | Mint a short-lived pair token (authenticated) |
|
|
98
|
-
| POST | `/api/pair/exchange` | Trade a pair token + client public key for a sealed API key (unauthenticated) |
|
|
99
|
-
|
|
100
|
-
## Remote Access (tunnels, funnels, proxies)
|
|
101
|
-
|
|
102
|
-
By default the streamer binds to `127.0.0.1:8766` and isn't reachable from the network. For the mobile app to pair from outside your LAN you need something forwarding HTTPS traffic to that local port. The fastest path is a Cloudflare quick-tunnel — no account, no domain, ~30 seconds:
|
|
103
|
-
|
|
104
|
-
```sh
|
|
105
|
-
# macOS / Linux / WSL / Git Bash
|
|
106
|
-
bash scripts/remote-access/cloudflare.sh
|
|
107
|
-
|
|
108
|
-
# Anywhere `pwsh` is installed (Windows native, or macOS/Linux via Homebrew)
|
|
109
|
-
pwsh scripts/remote-access/cloudflare.ps1
|
|
57
|
+
```bash
|
|
58
|
+
npm test # run tests
|
|
59
|
+
npm run lint # type-check + lint
|
|
60
|
+
npm run format # auto-format
|
|
61
|
+
npm run build # build ESM/CJS + copy migrations
|
|
62
|
+
npm run dev # watch mode
|
|
63
|
+
npm run migrate # apply SQLite migrations
|
|
64
|
+
npm run db:validate # check for missing/duplicate/orphaned project_id data
|
|
110
65
|
```
|
|
111
66
|
|
|
112
|
-
|
|
113
|
-
- **Cloudflare Tunnel:** [docs/guides/remote-access/cloudflare.md](docs/guides/remote-access/cloudflare.md) — quick-tunnel + named-tunnel + Access
|
|
114
|
-
- **Other providers:** [ngrok](docs/guides/remote-access/ngrok.md), [Tailscale Funnel](docs/guides/remote-access/tailscale-funnel.md), [VPS reverse proxy](docs/guides/remote-access/vps-reverse-proxy.md)
|
|
115
|
-
|
|
116
|
-
The Claude Code skill `setup-cloudflare-tunnel` runs the same script with prereq checks and named-tunnel guidance.
|
|
67
|
+
## Persistence
|
|
117
68
|
|
|
118
|
-
|
|
69
|
+
Conversation metadata is cached in SQLite at `~/.threadbase/cache/cache.db`, created and migrated automatically — no setup needed. Sessions are in-memory: a restart drops live PTYs, but history is on disk and any session can be resumed with `POST /api/sessions/resume`.
|
|
119
70
|
|
|
120
|
-
|
|
71
|
+
PostgreSQL is optional and only stores upload records today. Enable it by setting `THREADBASE_DATABASE_URL`; migrations run automatically.
|
|
121
72
|
|
|
122
|
-
|
|
73
|
+
## Architecture
|
|
123
74
|
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
tb-
|
|
75
|
+
```mermaid
|
|
76
|
+
graph LR
|
|
77
|
+
subgraph Mobile["tb-mobile"]
|
|
78
|
+
Client[Mobile / CLI client]
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
subgraph Streamer["tb-streamer"]
|
|
82
|
+
API[API layer<br/>src/api]
|
|
83
|
+
Core[Core engine<br/>server.ts]
|
|
84
|
+
WSHub[WS hub]
|
|
85
|
+
PTY[PTY sessions<br/>node-pty]
|
|
86
|
+
Watcher[Conversation watcher<br/>chokidar]
|
|
87
|
+
Cache[(SQLite cache<br/>cache.db)]
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
subgraph ScannerPkg["tb-scanner (npm dep)"]
|
|
91
|
+
Scanner[ConversationScanner]
|
|
92
|
+
SCache[(SQLite index<br/>index.db)]
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
Client -- HTTP --> API
|
|
96
|
+
Client -- WebSocket --> WSHub
|
|
97
|
+
API --> Core
|
|
98
|
+
Core --> WSHub
|
|
99
|
+
Core --> PTY
|
|
100
|
+
Core --> Watcher
|
|
101
|
+
Core --> Scanner
|
|
102
|
+
Watcher --> Cache
|
|
103
|
+
Watcher --> WSHub
|
|
104
|
+
PTY -- JSONL --> Watcher
|
|
105
|
+
PTY -- terminal_output --> WSHub
|
|
106
|
+
Scanner --> SCache
|
|
107
|
+
Scanner --> Cache
|
|
127
108
|
```
|
|
128
109
|
|
|
129
|
-
|
|
110
|
+
Three layers: **core engine** (`src/*.ts`) → **API layer** (`src/api/` + `src/index.ts`) → **CLI** (`cli/`).
|
|
130
111
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
112
|
+
- `POST /api/sessions/start` / `resume` spawns `claude` in a PTY; output streams to WebSocket clients as `terminal_output`, with a `terminal_replay` snapshot on subscribe.
|
|
113
|
+
- `SessionStore` tracks both PTY-managed sessions and externally-running `claude` processes discovered on disk.
|
|
114
|
+
- A chokidar-backed watcher tails conversation JSONL files into the SQLite cache, so list/search endpoints don't scan the filesystem.
|
|
115
|
+
- When the last WebSocket subscriber disconnects, a grace timer (default 4.5 min) puts the PTY on hold — history stays intact and it's resumable anytime.
|
|
134
116
|
|
|
135
|
-
|
|
117
|
+
More detail: [docs/how-it-works.md](docs/how-it-works.md) and [docs/architecture/](docs/architecture/README.md).
|
|
136
118
|
|
|
137
|
-
##
|
|
119
|
+
## REST API
|
|
138
120
|
|
|
139
|
-
|
|
121
|
+
Full endpoint reference: [docs/api-reference.md](docs/api-reference.md).
|
|
140
122
|
|
|
141
|
-
|
|
123
|
+
## Mobile Pairing (QR)
|
|
142
124
|
|
|
143
|
-
|
|
125
|
+
A pairing QR is printed on server start (skip with `--no-pair-qr`), or reprint one anytime with `tb-streamer pair`. Scanning it trades a single-use token for a sealed API key — the key itself never appears in the QR.
|
|
144
126
|
|
|
145
|
-
|
|
127
|
+
If the phone can't reach `localhost`, give it a reachable address via (in order of precedence) `--public-url`, `THREADBASE_PUBLIC_URL`, or `public_url:` in `server.yaml`. HTTPS is required except for `localhost`.
|
|
146
128
|
|
|
147
|
-
|
|
148
|
-
npm test # Run all tests
|
|
149
|
-
npm run lint # Type-check + Biome lint
|
|
150
|
-
npm run format # Auto-format
|
|
151
|
-
npm run build # Build ESM/CJS + copy SQLite + Postgres migrations
|
|
152
|
-
npm run dev # Watch mode
|
|
153
|
-
npm run migrate # Apply SQLite migrations to ~/.threadbase/cache/cache.db (override --db <path>)
|
|
154
|
-
npm run migrate:projects # Backfill projects + conversation.project_id from existing cache (idempotent)
|
|
155
|
-
npm run db:validate # Report conversations missing project_id, duplicate project paths, orphans
|
|
156
|
-
```
|
|
129
|
+
## Global CLI Commands
|
|
157
130
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
- `@threadbase-sh/scanner` + `@threadbase-sh/agent-types` — public npm packages (installed by `npm install`)
|
|
161
|
-
- `node-pty` — native PTY management
|
|
162
|
-
- `ws` — WebSocket server
|
|
163
|
-
- `better-sqlite3` — SQLite driver for the conversation cache
|
|
164
|
-
- `chokidar` — JSONL tail + directory watcher
|
|
165
|
-
- `zod` — runtime validation at HTTP and scanner boundaries
|
|
166
|
-
- `date-fns` — ISO timestamp parsing and comparison helpers
|
|
167
|
-
- `pg` — PostgreSQL client (lazy-loaded, only when `THREADBASE_DATABASE_URL` is configured)
|
|
168
|
-
- `commander` — CLI argument parsing
|
|
131
|
+
Deploying installs two equivalent global commands wrapping `~/.threadbase/cli.js`: `tb-streamer` and `threadbase-streamer`. Details: [docs/guides/deploy-internals.md](docs/guides/deploy-internals.md).
|
package/package.json
CHANGED