中文 · 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 roundsdisk_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 rounddocs/commands.md— verb referencedocs/configuration.md—agent-runner.tomlschemadocs/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
1 maintainer
Metadata
1 maintainer
Release files for cli-agent-runner 0.2.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cli_agent_runner-0.2.17.tar.gz | 600.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cli_agent_runner-0.2.17-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 849.1 kB
Release files / cli_agent_runner-0.2.17.tar.gz
| Download URL | cli_agent_runner-0.2.17.tar.gz |
|---|---|
| Size | 600.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8a2fbfae98a882b409acdd2ae813a648497264d9bfd1a7d4d399ac9fe6449d38
|
|
BLAKE2b-256 checksum How to use checksums |
65553b73d11b2fa309399332b14b7312d1103a4242b9b30d212cb7dd94baa12c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logRelease files / cli_agent_runner-0.2.17-py3-none-any.whl
| Download URL | cli_agent_runner-0.2.17-py3-none-any.whl |
|---|---|
| Size | 248.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16c0f42c7f1ea4a3672650360d89d77d893659d546643c7b02b010cc089a38ac
|
|
BLAKE2b-256 checksum How to use checksums |
4344e070700f60dba1bcb26a490cd772fece545dfe19805bf7cb483da2eeaba1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency log
