Execute Claude CLI with PTY handling, real-time tool visualization, and iterative execution support
npm install @rcrsr/claude-code-runnerDeterministic, scripted, unattended Claude Code execution with Rill scripting.
Like Ralph Wiggum, but smarter.
- Rich scripting — Fully scriptable with variables, conditionals, loops, and functions
- Walk away — Workflows can run unattended for hours if needed
- Treat Claude Code Skills as Functions — Call with arguments and get back return values throgh
- Fresh context — Each invocation starts with a clean slate
- Watch live — See your calls log activity as they execute
- Inspect later — Full session logs for debugging
- Node.js 18 or later
- Claude Code installed and authenticated
Claude Code Runner depends on node-pty for TTY terminal handling. You may need to install build tools first so the native modules can compile. See node-pty instructions for your platform.
Then install Claude Code Runner globally:
``bash`
npm install -g @rcrsr/claude-code-runner
`bash`
claude-code-runner prompt "Refactor the auth module to use async/await"
Run skills by name:
`bash`
claude-code-runner command review-code src/auth.ts
Example skill (.claude/skills/review-code/SKILL.md):
`markdown
---
description: Review code for issues
argument-hint:
model: sonnet
---
Review the code in $1 for:
- Security vulnerabilities
- Performance issues
- Code style violations
Output findings as a numbered list.
`
Template variables:
- $1, $2, $3... — Positional arguments$ARGUMENTS
- — All arguments joined with spaces
Frontmatter options:
- argument-hint — Defines required and optional [arg] argumentsmodel
- — Default model (CLI --model takes precedence)description
- — Skill/command description
Scripts use Rill, a scripting language designed for AI workflows. Rill provides:
- Variables & capture — Store Claude's output with :> operator(condition) ? action
- Conditionals — Branch logic with for
- Loops — Iterate with and while{$var}
- Functions — Reusable logic blocks
- String interpolation — Embed variables with syntax"""..."""
- Triple-quote strings — Multi-line prompts with
`bash`
claude-code-runner script workflow.rill src/api/
Example (code-review.rill):
`rill
---
description: Code review workflow
args: path: string
---
Suggest specific fixes with code examples.
"""
-> ccr::prompt :> $fixes
Host functions:
| Function | Description |
| ---------------------------- | ---------------------------------- |
|
ccr::prompt(text, model?) | Execute a Claude prompt |
| ccr::skill(name, args?) | Run a Claude Code skill |
| ccr::command(name, args?) | Run a Claude Code slash command |
| ccr::has_result(text) | Check if text contains ccr:result |
| ccr::get_result(text) | Extract from output |
| ccr::has_frontmatter(path) | Check if file has frontmatter |
| ccr::get_frontmatter(path) | Parse YAML frontmatter |
| ccr::file_exists(path) | Check if file exists |See docs/rill-scripting.md for the full scripting reference.
$3
| Option | Description |
| ----------------- | ------------------------------------------------------ |
|
--version, -V | Print version number |
| --model, -m | Specify Claude model (e.g., sonnet, opus, haiku) |
| --quiet | Minimal output (errors only) |
| --normal | Default output level |
| --verbose | Full output with details |
| --log | Enable file logging |
| --deaddrop | Enable DeadDrop streaming |Example with model selection:
`bash
claude-code-runner -m sonnet prompt "Explain this codebase"
`Results
Results let Claude communicate control flow decisions back to your scripts using XML:
`xml
details
`Result types are application-defined. Your script extracts and handles them:
`rill
ccr::prompt("Fix bugs. Signal if more remain.") :> $output
ccr::get_result($output) :> $resultDispatch on result type
$result.type -> [
repeat: log("More work needed"),
blocked: error $result.reason,
done: log("Complete")
]
`See docs/results.md for workflow patterns.
Exit Codes
For CI/CD integration:
| Code | Meaning |
| ---- | --------------------------------------- |
| 0 | Success |
| 1 | Error (script threw or Claude exited 1) |
Logs
Sessions are logged to
./logs/ with timestamped filenames when --log is specified.Documentation
- Getting Started
- CLI Reference
- Rill Scripting
- Results
- Examples
Development
`bash
npm run check # Run all checks (typecheck, lint, format, test)
npm run build # Build the project
npm test # Run tests
``MIT