claudraband
- Repo stars 283
- License MIT
- Author updated Live
- Author repo claudraband
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 94 / 100 · audit passed
- Author / version / license
- @halfwhey · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Bun
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: claudraband
description: Use claudraband CLI to control Claude Code sessions programmatically. Use when running, scriptin…
category: other
runtime: Node.js / Bun
---
# claudraband output preview
## PART A: Task fit
- Use case: 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.
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Commands / Send a prompt / Interactive REPL” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “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”.
- **02** When the source has headings, the agent prioritizes “Commands / Send a prompt / Interactive REPL” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/path`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Commands / Send a prompt / Interactive REPL”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: claudraband
description: Use claudraband CLI to control Claude Code sessions programmatically. Use when running, scriptin…
category: other
source: halfwhey/claudraband
---
# claudraband
## When to use
- Use claudraband CLI to control Claude Code sessions programmatically. Use when running, scripting, or automating Claud…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Commands / Send a prompt / Interactive REPL” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "claudraband" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Commands / Send a prompt / Interactive REPL
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js / Bun | read files, write/modify files, run shell commands | may access external network resources
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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 callplan-- plan only, no file editsauto-- bypass all permission checksacceptEdits-- auto-accept file editsdontAsk-- skip all confirmationsbypassPermissions-- 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+Cwhile prompt is running -- sends interrupt to Claude, waits for it to finishCtrl+Cwhile idle -- stops session and exitsCtrl+Din 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
sessionslist -- 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; prefertmuxorauto.--approve-allwith non-TTY stdin ----approve-alltakes precedence. Without it, all permissions are denied when stdin is not a TTY (e.g. piped input).
Decide Fit First
Design Intent
How To Use It
Boundaries And Review