中文 · 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)           │  13 detectors + auto-stop
├──────────────────────────────────────────┤
│ Layer 2: The Loop (serve)                │  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.

16 verbs

Lifecycle	Observation
init / install / uninstall	peek — state snapshot
start / stop / kill	watch — peek in a refresh loop
restart / status	monitor — 13 detectors, alerts, auto-stop
round / serve	events — query / stream events.jsonl
upgrade / migrate

Verb reference: docs/commands.md.

Defenses (built in)

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

Optionally pause the loop during off-hours: [schedule] run/pause windows gate serve (override with serve --ignore-schedule) — see the [schedule] section of docs/configuration.md.

Monitor: 13 detectors

Notify only: timeout_rate, hung, orphan_chain, disk_warning, mem_pressure, mem_pressure_gate_inert, mem_signal_unavailable, network_fail, rate_limit_active, anomaly_repetitive_active, supervisor_stale. mem_pressure also drives a separate serve-loop admission gate that defers or terminates rounds under real memory pressure — see docs/architecture.md.

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

Watch a remote host's event stream from your laptop with a managed ssh relay — one command instead of a hand-rolled ssh … ; sleep loop:

agent-runner monitor --host pi --mode events   # managed ssh relay, JSONL stdout

Detection stays on the host: --host with --mode anomaly | narrate | http exits with an error, since the detectors and auto-stop must keep working with your laptop closed. Full relay + SSH-trust mechanics: docs/runbook.md § "Remote event relay & SSH trust".

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.