@halfwhey/claudraband-core 0.3.0 → 0.5.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 (3) hide show
  1. package/README.md +74 -66
  2. package/dist/index.js +3 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,78 +1,68 @@
1
1
  <div align="center">
2
2
 
3
- # claudraband
3
+ # Claudraband
4
4
 
5
5
  Claude Code for the power user
6
6
 
7
- > Experimental: this project is still evolving and parts of it may break as Claude Code and ACP clients change.
7
+ > Experimental: this project is still evolving as Claude Code and ACP clients change.
8
8
 
9
- [Quick start](#quick-start) •
10
9
  [CLI](docs/cli.md) •
11
10
  [Library](docs/library.md) •
12
- [Examples](#examples) •
13
- [Troubleshooting](#troubleshooting)
11
+ [Daemon API](docs/daemon-api.md) •
12
+ [Examples](examples/)
14
13
 
15
14
  </div>
16
15
 
17
- `claudraband` wraps a Claude Code TUI in a controlled terminal to enable extended workflows. This project provides:
16
+ `claudraband` wraps the official Claude Code TUI in a controlled terminal so you can keep sessions alive, resume them later, answer pending prompts, expose them through a daemon, or drive them through ACP.
18
17
 
19
- - Resumable non-interactive workflows. Essentially `claude -p` with session support: `cband continue <session-id> 'what was the result of the research?'`
20
- - HTTP server to remotely control a Claude Code session: `cband serve --port 1234`
21
- - ACP server to use with alternative frontends such as Zed or Toad (https://github.com/batrachianai/toad): `cband acp --model haiku`
22
- - TypeScript library so you can integrate these workflows into your own application.
18
+ It provides:
23
19
 
24
- ## Caveats
20
+ - Resumable non-interactive workflows. Essentially claude -p with session support: cband continue <session-id> 'what was the result of the research?'
21
+ - An http daemon for remote or headless session control
22
+ - An ACP server for editor and alternate frontend integration
23
+ - A TypeScript library for building these workflows into your own tools
24
+
25
+ Caveats
25
26
 
26
27
  - This is not a replacement for the Claude SDK. It is geared toward personal, ad-hoc usage.
27
28
  - We do not touch OAuth and we do not bypass the Claude Code TUI. You must authenticate through Claude Code, and every interaction runs through a real Claude Code session.
28
29
 
29
- ## Requirements
30
+
31
+ ## Setup
32
+
33
+ Requirements:
30
34
 
31
35
  - Node.js or Bun
32
36
  - An already authenticated Claude Code
33
- - `tmux` if you want visible persistent local sessions
37
+ - `tmux` for the first-class local and daemon-backed workflow
34
38
 
35
- ## Install
39
+ Install or run:
36
40
 
37
41
  ```sh
38
- # run without installing globally
42
+ # one-off
39
43
  npx @halfwhey/claudraband "review the staged diff"
44
+ bunx @halfwhey/claudraband "review the staged diff"
40
45
 
41
- # or install it once
46
+ # install once
42
47
  npm install -g @halfwhey/claudraband
43
48
  ```
44
49
 
45
- If you prefer Bun:
46
-
47
- ```sh
48
- bunx @halfwhey/claudraband "review the staged diff"
49
- ```
50
-
51
- `claudraband` installs a pinned Claude Code version, `@anthropic-ai/claude-code@2.1.96`, as a dependency for compatibility. It will be bumped over time. If you need to point at a different Claude binary for debugging or compatibility work, set `CLAUDRABAND_CLAUDE_PATH`.
52
-
50
+ The package installs both `claudraband` and `cband`. `cband` is the recommended shorthand. The package bundles Claude Code `@anthropic-ai/claude-code@2.1.96`; set `CLAUDRABAND_CLAUDE_PATH` if you need to override the binary.
53
51
 
54
- ## Quick start
52
+ ## Quick Start
55
53
 
56
- The package installs both `cband` and `claudraband`. The shorter `cband` binary is the recommended CLI. The two first-class ways to use `cband` are:
54
+ The two first-class paths are local `tmux` sessions and daemon-backed sessions.
57
55
 
58
- - local persistent sessions with `tmux`
59
- - headless persistent sessions with `serve`
60
-
61
- ### Visible persistent sessions with `tmux`
56
+ ### Local persistent sessions
62
57
 
63
58
  ```sh
64
59
  cband "audit the last commit and tell me what looks risky"
65
-
66
60
  cband sessions
67
-
68
61
  cband continue <session-id> "keep going"
69
-
70
- # if Claude is waiting on a choice
71
62
  cband continue <session-id> --select 2
72
- cband continue <session-id> --select 3 "xyz"
73
63
  ```
74
64
 
75
- ### Headless persistent sessions with `serve`
65
+ ### Daemon-backed sessions
76
66
 
77
67
  ```sh
78
68
  cband serve --host 127.0.0.1 --port 7842
@@ -81,73 +71,91 @@ cband attach <session-id>
81
71
  cband continue <session-id> --select 2
82
72
  ```
83
73
 
84
- The daemon now defaults to `tmux`, just like the local first-class path. Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically.
85
-
86
- `--backend xterm` still exists, but it is experimental while we improve it.
87
-
88
- ### Using the CLI without tmux or server (experimental)
89
-
90
- If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. This backend is **experimental** and slower than tmux. It is useful for one-off runs, but it is not a good default for interactive follow-up because the session is not kept alive between commands.
91
-
92
- The xterm backend cannot handle Claude Code's initial startup prompts (trust folder, bypass permissions confirmation). You must disable these before using it:
74
+ The daemon defaults to using `tmux` as the terminal runtime, just like the local path. Use `--connect` only when creating a new daemon-backed session; after that, tracked `continue`, `attach`, and `sessions` route through the recorded live owner automatically.
93
75
 
94
- - `-c "--dangerously-skip-permissions"`
95
- - `--permission-mode bypassPermissions`
76
+ ## Experimental Xterm Backend
96
77
 
97
- Without `tmux` or server mode, `cband` shuts down Claude Code after each command finishes and starts it again on the next one. If the last output was a question for the user, that question will not survive well across the next resume. Interactive question flows work best with persistent sessions.
78
+ `--backend xterm` exists for local or daemon use, but it is experimental and slower than `tmux`. Use it when you need a headless fallback, not as the default path for long-lived interactive work. See [docs/cli.md](docs/cli.md) for current caveats and backend behavior.
98
79
 
99
- ### ACP and editor integration
80
+ ## ACP
100
81
 
101
82
  Use ACP when another tool wants to drive Claude through `claudraband`.
102
83
 
103
84
  ```sh
104
85
  cband acp --model opus
105
86
 
106
- # for example with toad
87
+ # example: toad
107
88
  uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'
108
89
  ```
109
90
 
110
- Some ACP clients still have limitations around resuming existing sessions. `claudraband` itself supports session follow and resume as part of the ACP protocol, but the frontend you put on top may not expose all of that yet.
91
+ Editor and ACP client support varies by frontend, but `claudraband` itself supports session follow and resume through ACP.
111
92
 
112
- ## Session model
93
+ ## Session Model
113
94
 
114
95
  Live sessions are tracked in `~/.claudraband/`.
115
96
 
116
- - `cband sessions` shows only live tracked sessions, either hosted by tmux directly or by the daemon.
117
- - `continue` can resume an existing Claude Code session even when it is no longer live, but `attach` only works on live sessions.
118
- - `sessions close ...` closes live sessions hosted by tmux directly or by the daemon
119
- - `sessions close --all` will close all live sessions controlled by Claudraband
97
+ - `cband sessions` lists live tracked sessions
98
+ - `continue` can resume an existing Claude Code session even when it is no longer live
99
+ - `attach` only works on live sessions
100
+ - `sessions close ...` closes live tracked sessions, either local or daemon-backed
120
101
 
121
102
  ## Examples
122
103
 
123
104
  ### Self-interrogation
124
105
 
125
- I have a Claude Code hook that saves the session id that was involved in a commit so I can ask it questions about the commit later. In this workflow, Claude can use `claudraband` to interrogate that older session and justify the choices it made.
106
+ Claude can interrogate an older Claude session and justify the choices it made.
126
107
 
127
108
  ![Claude interrogating an older Claude session through claudraband](assets/self-interrogate.png)
128
109
 
129
110
  ### Toad via ACP
130
111
 
131
- Toad can use `claudraband acp` to be an alternative frontend for Claude Code.
112
+ Toad can use `claudraband acp` as an alternative frontend for Claude Code.
132
113
 
133
114
  ![Toad using claudraband ACP as an alternative frontend](assets/toad-acp.png)
134
115
 
135
- That UI is backed by a real Claude Code pane underneath.
116
+ That UI is still backed by a real Claude Code pane underneath.
136
117
 
137
118
  ![Backing Claude Code pane for the Toad ACP session](assets/toad-claude-pane.png)
138
119
 
139
120
  ### Zed via ACP
140
121
 
141
- Zed can also use `claudraband acp` to be an alternative frontend.
122
+ Zed can also use `claudraband acp` as an alternative frontend.
142
123
 
143
124
  ![Zed using claudraband ACP as an alternative frontend](assets/zed-acp.png)
144
125
 
145
- ## Library use
126
+ ## Library
146
127
 
147
- Runnable TypeScript examples live in [`examples/`](examples):
128
+ Runnable TypeScript examples live in [`examples/`](examples/):
148
129
 
149
- - [`examples/code-review.ts`](examples/code-review.ts) starts a session, asks for a review, and prints the result
150
- - [`examples/multi-session.ts`](examples/multi-session.ts) runs multiple Claude sessions in parallel
151
- - [`examples/session-journal.ts`](examples/session-journal.ts) resumes a session and writes a simple journal
130
+ - [`examples/code-review.ts`](examples/code-review.ts)
131
+ - [`examples/multi-session.ts`](examples/multi-session.ts)
132
+ - [`examples/session-journal.ts`](examples/session-journal.ts)
152
133
 
153
- For the full TypeScript API, see [docs/library.md](docs/library.md).
134
+ For the full API, see [docs/library.md](docs/library.md). For CLI details, see [docs/cli.md](docs/cli.md). For raw daemon endpoints, see [docs/daemon-api.md](docs/daemon-api.md).
135
+
136
+ ## Cheat Sheet
137
+
138
+ ```sh
139
+ # install or run once
140
+ npx @halfwhey/claudraband "review the staged diff"
141
+ bunx @halfwhey/claudraband "review the staged diff"
142
+ npm install -g @halfwhey/claudraband
143
+
144
+ # local persistent sessions
145
+ cband "audit the last commit"
146
+ cband sessions
147
+ cband sessions close --all # close all claudraband controlled sessions
148
+ cband continue <session-id> "keep going"
149
+
150
+ # answer pending prompts
151
+ cband continue <session-id> --select 2
152
+ cband continue <session-id> --select 3 "xyz"
153
+
154
+ # daemon mode
155
+ cband serve --host 127.0.0.1 --port 7842
156
+ cband --connect localhost:7842 "start a migration plan"
157
+ cband attach <session-id>
158
+
159
+ # ACP
160
+ cband acp --model opus
161
+ ```
package/dist/index.js CHANGED
@@ -2043,7 +2043,9 @@ ${prompt.options.map((option) => `${option.number}:${option.label}`).join(`
2043
2043
  if (this.lastNativePermissionOutcome === "handled" || this.lastNativePermissionOutcome === "consumed") {
2044
2044
  return "pending_clear";
2045
2045
  }
2046
- return this.lastNativePermissionOutcome;
2046
+ if (this.lastNativePermissionOutcome !== "deferred") {
2047
+ return this.lastNativePermissionOutcome;
2048
+ }
2047
2049
  }
2048
2050
  const decision = await this.resolvePermission({
2049
2051
  source: "native_prompt",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@halfwhey/claudraband-core",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "TypeScript runtime for controlling local Claude Code sessions through a real terminal.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",