Claude Code Runner

Deterministic, scripted, unattended Claude Code execution with Rill scripting.

Why Use This?

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

Prerequisites

- Node.js 18 or later
- Claude Code installed and authenticated

Installation

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
`

Usage

$3

`bash
claude-code-runner prompt "Refactor the auth module to use async/await"
`

$3

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: [severity]
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] arguments
- model — Default model (CLI --model takes precedence)
- description — Skill/command description

$3

Scripts use Rill, a scripting language designed for AI workflows. Rill provides:

- Variables & capture — Store Claude's output with :> operator
- Conditionals — Branch logic with (condition) ? action
- Loops — Iterate with for and while
- Functions — Reusable logic blocks
- String interpolation — Embed variables with {$var} 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
---

Analyze the code

ccr::prompt("Review the code in {$path} for bugs") :> $issues

Get fixes based on issues found

"""
Based on these issues:
{$issues}

Suggest specific fixes with code examples.
"""
-> ccr::prompt :> $fixes

Summarize

ccr::prompt("Summarize: Issues: {$issues} Fixes: {$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) :> $result

Dispatch 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
``

License

MIT