中文 · English

agent-runner

A restart-on-exit supervisor for autonomous coding CLIs. Ships presets for Claude Code, aider, gemini, codewhale, kimi and pi; any prompt-arg CLI via custom config. Spawn the agent round-after-round under defenses that prevent the failure modes that bite in production: stuck rounds, orphan commits, OAuth burn loops, full disks, runaway memory.

┌──────────────────────────────────────────┐
│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
├──────────────────────────────────────────┤
│ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
├──────────────────────────────────────────┤
│ Layer 1: The Round (round)               │  one agent invocation
└──────────────────────────────────────────┘

Install

pip install cli-agent-runner

The installed CLI command is agent-runner (the PyPI distribution name is prefixed for namespace disambiguation; the import name and command are not).

Quick start

cd your-project
agent-runner init                 # scaffold agent-runner.toml + prompts/main.md
$EDITOR agent-runner.toml         # point agent.command at your CLI
agent-runner install --monitor    # systemd user units for serve + monitor
agent-runner status               # confirm running
agent-runner peek                 # snapshot of project state
agent-runner monitor              # live anomaly detection

Full walkthrough: docs/quickstart.md.

15 verbs

Verb reference: docs/commands.md.

Defenses (built in)

12 named defenses, structured as data — see agent-runner peek --select defenses. Each carries the historical incident it codifies and the invariant test that guards it. Highlights:

• round_timeout_s — hard wall, never the agent's word on when to stop
• process_group_isolation — kill the round, not just the parent
• orphan_stash_idempotency_s — no 3-stashes-per-second pile-ups
• sha_locked_stash — stash@{N} indices drift; SHAs don't
• set_diff_classification — line-set comparison, not unified-diff +/- scan
• startup_smoke_check — refuse to run with a clearly-truncated prompt

Full list and rationale: docs/architecture.md.

Monitor: 11 detectors

Notify only: timeout_rate, hung, orphan_chain, disk_warning, mem_pressure, network_fail, rate_limit_active, anomaly_repetitive_active, supervisor_stale.

Auto-stop the service (continuing is harmful):

• oauth_fail — burning API quota on auth-rejected rounds
• disk_critical — writing to a near-full disk risks corruption

Runs against the supervised project's local logs:

agent-runner monitor                  # 30s poll
agent-runner monitor --json | jq -c   # pipe to downstream consumers

Remote monitoring is unsupported in this version: monitor --host <alias> cannot read a remote host's round logs or events, so it exits with an error at startup instead of watching an empty world and reporting healthy. Run the monitor on the supervised host itself (ssh <alias>, then agent-runner monitor). See docs/runbook.md § "Remote monitor & SSH trust" — the SSH trust boundary applies to any agent-runner command you drive over ssh.

Documentation

• docs/quickstart.md — 5-step install + first round
• docs/commands.md — verb reference
• docs/configuration.md — agent-runner.toml schema
• docs/runbook.md — operator troubleshooting (OAuth, disk, orphan)
• docs/architecture.md — 3-layer model, defenses-as-data

Development

git clone https://github.com/wan9yu/cli-agent-runner.git
cd cli-agent-runner
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

./build.sh check                          # full local-CI sweep
./build.sh test                           # unit + integration only
AGENT_RUNNER_E2E_PI=1 ./build.sh e2e      # opt-in pi e2e (needs ssh alias `pi`)

Some docs/*.md blocks are generated from code — ./build.sh docs rewrites the <!-- gen:* --> regions, and ./build.sh check verifies they are fresh.

POSIX-only (Linux, macOS). Tested under Python 3.11+ on x86_64 and aarch64.

License

Apache License 2.0.