Claudraband：Claude Code 高级用户工具集

Claude Code 面向高级用户的工具

实验性：该项目仍在随 Claude Code 和 ACP 客户端的变化而演进。

CLI • 库 • 守护进程 API • Docker • 示例

claudraband 在受控终端中包装了官方 Claude Code TUI，让你可以保持会话活跃、稍后恢复会话、回答待处理的提示、通过守护进程暴露，或通过 ACP 驱动。

可恢复的非交互工作流。本质上是带会话支持的 claude -p：cband prompt --session <session-id> 'what was the result of the research?'

HTTP 守护进程用于远程或无头会话控制

ACP 服务器用于编辑器和备用前端集成

TypeScript 库用于将这些工作流构建到你自己的工具中

这不是 Claude SDK 的替代品。它面向个人、临时使用。

我们不涉及 OAuth，也不绕过 Claude Code TUI。你必须通过 Claude Code 进行认证，每次交互都通过真实的 Claude Code 会话运行。

所需：已认证的 Claude Code

运行时：tmux 用于一流的本地和守护进程支持的工作流

# one-off
npx @halfwhey/claudraband "review the staged diff"
bunx @halfwhey/claudraband "review the staged diff"

# install once
npm install -g @halfwhey/claudraband

该软件包安装 claudraband 和 cband。cband 是推荐的简写。该软件包包含 Claude Code @anthropic-ai/claude-code@2.1.96；如果需要覆盖二进制文件，请设置 CLAUDRABAND_CLAUDE_PATH。

mkdir -p "$PWD/claude-account"

# one-time onboarding for the mounted Claude account bundle
docker run --rm -it \
  -v "$PWD/claude-account:/claude-account" \
  ghcr.io/halfwhey/claudraband:latest claude

# start the daemon with the same mounted account bundle
docker run --rm -d --name claudraband \
  -p 7842:7842 \
  -v "$PWD/claude-account:/claude-account" \
  ghcr.io/halfwhey/claudraband:latest serve

cband --connect localhost:7842 "hello from docker"

如果 Claude 启动时出现本机启动权限提示，用 cband prompt --session <session-id> --select <option> 来回答。有关更多容器详情，请参阅 docs/docker.md。

本地和守护进程工作流

两个一流的路径是本地 tmux 会话和守护进程支持的会话。

本地持久会话

cband "audit the last commit and tell me what looks risky"
cband sessions
cband prompt --session <session-id> "keep going"
cband prompt --session <session-id> --select 2
cband watch --session <session-id>
cband interrupt --session <session-id>

守护进程支持的会话

cband serve --host 127.0.0.1 --port 7842
cband --connect localhost:7842 "start a migration plan"
cband attach <session-id>
cband prompt --session <session-id> --select 2

守护进程默认使用 tmux 作为终端运行时，就像本地路径一样。仅在创建新的守护进程支持的会话时使用 --connect；之后，prompt、send、watch、interrupt、attach 和 sessions 通过记录的实时所有者自动路由。

实验性 xterm.js 后端

--backend xterm 适用于本地或守护进程使用，但它是实验性的，比 tmux 慢。仅在需要无头回退时使用它，而不是作为长期交互工作的默认路径。有关当前的注意事项和后端行为，请参阅 docs/cli.md。

ACP 服务器

当另一个工具想通过 claudraband 驱动 Claude 时，使用 ACP。

cband acp --model opus

# example: toad
uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'

编辑器和 ACP 客户端支持因前端而异，但 claudraband 本身通过 ACP 支持会话跟踪和恢复。

会话跟踪

实时会话在 ~/.claudraband/ 中被跟踪。

cband sessions 列出实时跟踪的会话

prompt --session <id> 和 send --session <id> 自动恢复已保存的会话，即使它不再活跃

watch、interrupt、status、last 按 id 目标会话

attach 仅适用于活跃会话

sessions close ... 关闭实时跟踪的会话，本地或守护进程支持

集成

Claude 可以询问较早的 Claude 会话并证明所做选择的合理性。

Toad 可以使用 claudraband acp 作为 Claude Code 的替代前端。

该 UI 仍由下面的真实 Claude Code 窗格支持。

Zed 也可以使用 claudraband acp 作为替代前端。

库

可运行的 TypeScript 示例位于 examples/：

• examples/code-review.ts
• examples/multi-session.ts
• examples/session-journal.ts

有关完整 API，请参阅 docs/library.md。有关 CLI 详情，请参阅 docs/cli.md。有关原始守护进程端点，请参阅 docs/daemon-api.md。

快速参考

# install or run once
npx @halfwhey/claudraband "review the staged diff"
bunx @halfwhey/claudraband "review the staged diff"
npm install -g @halfwhey/claudraband

# local persistent sessions
cband "audit the last commit"
cband sessions
cband sessions close --all # close all claudraband controlled sessions
cband prompt --session <session-id> "keep going"
cband send --session <session-id> "fire and forget"
cband watch --session <session-id>
cband interrupt --session <session-id>
cband status --session <session-id>
cband last --session <session-id>

# answer pending prompts
cband prompt --session <session-id> --select 2
cband prompt --session <session-id> --select 3 "xyz"

# daemon mode
cband serve --host 127.0.0.1 --port 7842
cband --connect localhost:7842 "start a migration plan"
cband attach <session-id>

# ACP
cband acp --model opus