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 <ccr:result type="..."/>
• 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:

npm install -g @rcrsr/claude-code-runner

Usage

prompt — Run a single prompt

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

skill — Run a Claude Code Skill file

Run skills by name:

claude-code-runner command review-code src/auth.ts

Example skill (.claude/skills/review-code/SKILL.md):

---
description: Review code for issues
argument-hint: <file> [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 <arg> and optional [arg] arguments
• model — Default model (CLI --model takes precedence)
• description — Skill/command description

script — Run multi-phase workflows

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 """..."""

claude-code-runner script workflow.rill src/api/

Example (code-review.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 <ccr:result> 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.

Options

| 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:

claude-code-runner -m sonnet prompt "Explain this codebase"

Results

Results let Claude communicate control flow decisions back to your scripts using XML:

<ccr:result type="repeat"/>
<ccr:result type="done"/>
<ccr:result type="blocked" reason="...">details</ccr:result>

Result types are application-defined. Your script extracts and handles them:

ccr::prompt("Fix bugs. Signal <ccr:result type='repeat'/> 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

npm run check    # Run all checks (typecheck, lint, format, test)
npm run build    # Build the project
npm test         # Run tests

License

MIT