中文 · 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

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

Verb reference: docs/commands.md.

Defenses (built in)

13 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

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

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

The relay reconnects with --since <last ts> so a dropped link replays its gap, gives up (exit 1) once the outage passes remote_failure_tolerance_s, and kills the ssh process group on exit so no orphan tree is left behind.

Detection stays on the host. --host with --mode anomaly | narrate | http exits with an error: the detectors read the supervised host's logs and auto-stop its service, which must keep working with your laptop closed. Run the monitor there (ssh <alias>, then agent-runner monitor) and relay its events here. See docs/runbook.md § "Remote event relay & 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  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.

Metadata

Release files for cli-agent-runner 0.2.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cli-agent-runner 0.2.7
File	Size	Uploaded
cli_agent_runner-0.2.7.tar.gz	417.7 kB	Aug 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cli-agent-runner 0.2.7
File	Interpreter	ABI	Platform	Reset
cli_agent_runner-0.2.7-py3-none-any.whl 148.6 kB Aug 25, 2026	Python 3	none	any	Details

Total release size: 566.3 kB

Release files / cli_agent_runner-0.2.7.tar.gz

Download URL	cli_agent_runner-0.2.7.tar.gz
Size	417.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`5e6ccf7596c5bde3fb86d9448ebdb1b81d96d9d358062c05d294dcfd3406f345`
BLAKE2b-256 checksum How to use checksums	`a7cac79ecb4d024cddf257574b966facf7015872a91830d08bbba155390561ce`
Upload date	Aug 25, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wan9yu/cli-agent-runner
Publishing commit: github.com/wan9yu/cli-agent-runner/tree/11c954ae8e92e1a1649619e911ae2ec754e1a293

Workflow

Publishing configuration: github.com/wan9yu/cli-agent-runner/blob/11c954ae8e92e1a1649619e911ae2ec754e1a293/.github/workflows/release.yml
Publishing logs: github.com/wan9yu/cli-agent-runner/actions/runs/32878500825/attempts/1

Artifact

Subject: cli_agent_runner-0.2.7.tar.gz
SHA-256 checksum: 5e6ccf7596c5bde3fb86d9448ebdb1b81d96d9d358062c05d294dcfd3406f345 Verifying attestations

Release files / cli_agent_runner-0.2.7-py3-none-any.whl

Download URL	cli_agent_runner-0.2.7-py3-none-any.whl
Size	148.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9f1f77a93d7a02fb47b5aebde3f03d157e6dd21d54887ae2f32c0759370f51a9`
BLAKE2b-256 checksum How to use checksums	`563aaa6629512b9d6a198839588f07e47476b3433afef3ca2f01262b322a91fd`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wan9yu/cli-agent-runner
Publishing commit: github.com/wan9yu/cli-agent-runner/tree/11c954ae8e92e1a1649619e911ae2ec754e1a293

Workflow

Publishing configuration: github.com/wan9yu/cli-agent-runner/blob/11c954ae8e92e1a1649619e911ae2ec754e1a293/.github/workflows/release.yml
Publishing logs: github.com/wan9yu/cli-agent-runner/actions/runs/32878500825/attempts/1

Artifact

Subject: cli_agent_runner-0.2.7-py3-none-any.whl
SHA-256 checksum: 9f1f77a93d7a02fb47b5aebde3f03d157e6dd21d54887ae2f32c0759370f51a9 Verifying attestations