@halfwhey/claudraband-core 0.1.0 → 0.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 +149 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# claudraband
|
|
4
|
+
|
|
5
|
+
Claude Code for the power user
|
|
6
|
+
|
|
7
|
+
> Experimental: this project is still evolving and parts of it may break as Claude Code and ACP clients change.
|
|
8
|
+
|
|
9
|
+
[Quick start](#quick-start) •
|
|
10
|
+
[CLI](docs/cli.md) •
|
|
11
|
+
[Library](docs/library.md) •
|
|
12
|
+
[Examples](#examples) •
|
|
13
|
+
[Troubleshooting](#troubleshooting)
|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
`claudraband` wraps a Claude Code TUI in a controlled terminal to enable extended workflows. This project provides:
|
|
18
|
+
|
|
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.
|
|
23
|
+
|
|
24
|
+
## Caveats
|
|
25
|
+
|
|
26
|
+
- This is not a replacement for the Claude SDK. It is geared toward personal, ad-hoc usage.
|
|
27
|
+
- 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
|
+
## Requirements
|
|
30
|
+
|
|
31
|
+
- Node.js or Bun
|
|
32
|
+
- An already authenticated Claude Code
|
|
33
|
+
- `tmux` if you want visible persistent local sessions
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
# run without installing globally
|
|
39
|
+
npx @halfwhey/claudraband "review the staged diff"
|
|
40
|
+
|
|
41
|
+
# or install it once
|
|
42
|
+
npm install -g @halfwhey/claudraband
|
|
43
|
+
```
|
|
44
|
+
|
|
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
|
+
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
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:
|
|
57
|
+
|
|
58
|
+
- local persistent sessions with `tmux`
|
|
59
|
+
- headless persistent sessions with `serve`
|
|
60
|
+
|
|
61
|
+
### Visible persistent sessions with `tmux`
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
cband "audit the last commit and tell me what looks risky"
|
|
65
|
+
|
|
66
|
+
cband sessions
|
|
67
|
+
|
|
68
|
+
cband continue <session-id> "keep going"
|
|
69
|
+
|
|
70
|
+
# if Claude is waiting on a choice
|
|
71
|
+
cband continue <session-id> --select 2
|
|
72
|
+
cband continue <session-id> --select 3 "xyz"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Headless persistent sessions with `serve`
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
cband serve --host 127.0.0.1 --backend xterm --port 7842
|
|
79
|
+
cband --connect localhost:7842 "start a migration plan"
|
|
80
|
+
cband attach <session-id>
|
|
81
|
+
cband continue <session-id> --select 2
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically. `attach` is especially useful here because it gives you a simple REPL for a headless xterm.js session.
|
|
85
|
+
|
|
86
|
+
### Using the CLI without tmux or server
|
|
87
|
+
|
|
88
|
+
If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. That mode 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. It only works properly when Claude itself can proceed without an interactive permission prompt. Use one of:
|
|
89
|
+
|
|
90
|
+
- `-c "--dangerously-skip-permissions"`
|
|
91
|
+
- `--permission-mode bypassPermissions`
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
### ACP and editor integration
|
|
96
|
+
|
|
97
|
+
Use ACP when another tool wants to drive Claude through `claudraband`.
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
cband acp --model opus
|
|
101
|
+
|
|
102
|
+
# for example with toad
|
|
103
|
+
uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
## Session model
|
|
109
|
+
|
|
110
|
+
Live sessions are tracked in `~/.claudraband/`.
|
|
111
|
+
|
|
112
|
+
- `cband sessions` shows only live tracked sessions, either hosted by tmux or the xterm.js daemon.
|
|
113
|
+
- `continue` can resume an existing Claude Code session even when it is no longer live, but `attach` only works on live sessions.
|
|
114
|
+
- `sessions close ...` closes live sessions hosted by tmux or the xterm.js daemon
|
|
115
|
+
- `sessions close --all` will close all live sessions controlled by Claudraband
|
|
116
|
+
|
|
117
|
+
## Examples
|
|
118
|
+
|
|
119
|
+
### Self-interrogation
|
|
120
|
+
|
|
121
|
+
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.
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
### Toad via ACP
|
|
126
|
+
|
|
127
|
+
Toad can use `claudraband acp` to be an alternative frontend for Claude Code.
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
That UI is backed by a real Claude Code pane underneath.
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
### Zed via ACP
|
|
136
|
+
|
|
137
|
+
Zed can also use `claudraband acp` to be an alternative frontend.
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
## Library use
|
|
142
|
+
|
|
143
|
+
Runnable TypeScript examples live in [`examples/`](examples):
|
|
144
|
+
|
|
145
|
+
- [`examples/code-review.ts`](examples/code-review.ts) starts a session, asks for a review, and prints the result
|
|
146
|
+
- [`examples/multi-session.ts`](examples/multi-session.ts) runs multiple Claude sessions in parallel
|
|
147
|
+
- [`examples/session-journal.ts`](examples/session-journal.ts) resumes a session and writes a simple journal
|
|
148
|
+
|
|
149
|
+
For the full TypeScript API, see [docs/library.md](docs/library.md).
|
package/package.json
CHANGED