claudraband

name

claudraband

description

Use claudraband CLI to control Claude Code sessions programmatically. Use when running, scripting, or automating Claude Code via the claudraband CLI — sending prompts, listing/resuming sessions, or working in interactive REPL mode. Triggers on any mention of claudraband, claudraband-cli, npx claudraband, bunx claudraband, or automating Claude Code sessions. Used when you need to ask yourself (Claude) a question

Claudraband CLI

Claudraband spawns Claude Code in a hidden shared tmux session, tails its JSONL log, and provides a clean command-line interface for sending prompts, streaming output, and managing sessions.

Local built binary: node packages/claudraband-cli/dist/bin.js or bun packages/claudraband-cli/dist/bin.js

Published binary: claudraband via npx @halfwhey/claudraband or bunx @halfwhey/claudraband

---

Commands

Send a prompt

node packages/claudraband-cli/dist/bin.js "your prompt here"

Positional args after flags are concatenated as the prompt. Blocks until Claude finishes all tool calls, then exits.

Interactive REPL

node packages/claudraband-cli/dist/bin.js -i

Starts a read-eval-print loop. Send multiple prompts to the same session without restarting. Exit with Ctrl+D, cancel current prompt with Ctrl+C.

List sessions

node packages/claudraband-cli/dist/bin.js sessions [--cwd <dir>]

Lists resumable sessions for a directory (defaults to cwd). Output per line: <sessionId> <date> <title>.

Sessions are stored at ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl. A session only appears here if the file is >= 100 bytes.

Resume a session

node packages/claudraband-cli/dist/bin.js resume <sessionId> [prompt...]

Resumes a previous session by UUID. Optionally send a new prompt immediately.

---

Flags

Flag	Short	Default	Description
--help	-h	-	Show usage and exit
--interactive	-i	false	REPL mode
--cwd <dir>	-	cwd	Working directory for session
--claude "<flags>"	-c	-	Claude CLI launch flags, e.g. --model sonnet --effort high
--approve-all	-	false	Auto-select first permission option
--terminal-backend <backend>	-	auto	auto, tmux, or xterm
--debug	-	false	Debug logging to stderr

Permission modes

• default -- prompt user for each tool call
• plan -- plan only, no file edits
• auto -- bypass all permission checks
• acceptEdits -- auto-accept file edits
• dontAsk -- skip all confirmations
• bypassPermissions -- dangerously skip everything

---

Session lifecycle

tmux-backed sessions share a tmux session named claudraband-working-session. Each Claude session gets its own tmux window named with the Claude session ID, and the CLI sends prompts into that window's pane while tailing the JSONL log for events.

Turn completion: detected via 3-second idle timeout after Claude sends a response with no outstanding tool calls. This is not a hard delay -- the idle timer only starts after a response arrives.

Interruption:

• Ctrl+C while prompt is running -- sends interrupt to Claude, waits for it to finish
• Ctrl+C while idle -- stops session and exits
• Ctrl+D in REPL -- exits the loop and stops the session

---

Permission prompts

When Claude requests a tool permission, the CLI prints:

Permission: <title>
  <description>
  1. <option> (<kind>)
  2. <option> (<kind>)

With --approve-all, the first option is selected automatically and prints -> auto: <option name>.

If stdin is not a TTY and --approve-all is not set, permission is denied automatically.

Tool kinds shown in prompts: read, edit, execute, search, fetch, think, other.

---

Output

Events stream to stdout with ANSI color:

• Grey -- assistant text
• Bold yellow -- tool call: > ToolName
• Green -- tool result: + ToolName
• Red -- error: ! message
• Dimmed -- thinking blocks and system messages

Use --debug to send diagnostic logs to stderr without polluting stdout.

---

Common examples

# One-shot prompt
node packages/claudraband-cli/dist/bin.js "summarize the last 5 commits"

# Interactive with opus
node packages/claudraband-cli/dist/bin.js -i --claude "--model opus"

# Auto-approve all permissions
node packages/claudraband-cli/dist/bin.js --approve-all --claude "--permission-mode auto" "run tests and fix failures"

# Resume a session and continue
node packages/claudraband-cli/dist/bin.js sessions
node packages/claudraband-cli/dist/bin.js resume 550e8400-e29b-41d4-a716-446655440000 "implement what you planned"

# Different working directory
node packages/claudraband-cli/dist/bin.js --cwd /path/to/repo "what does this do?"

# Debug mode to trace events
node packages/claudraband-cli/dist/bin.js --debug "write a function" 2>debug.log

---

Gotchas

• No prompt and no -i -- exits immediately with an error. Always provide one or the other.
• Session not in sessions list -- file may be < 100 bytes (e.g. aborted immediately). Check ~/.claude/projects/ directly.
• --claude "--permission-mode ..." change mid-session -- requires restarting the session (Claude Code reloads on mode change). Don't change it after the first prompt if you need consistency.
• --terminal-backend xterm -- fallback for environments without tmux. Slightly less reliable for long sessions; prefer tmux or auto.
• --approve-all with non-TTY stdin -- --approve-all takes precedence. Without it, all permissions are denied when stdin is not a TTY (e.g. piped input).