中文 · 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)                │  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` — 11 detectors, alerts, auto-stop
`round` / `serve`	`events` — query / stream events.jsonl
`upgrade` / `migrate`

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.

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

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.8
File	Size	Uploaded
cli_agent_runner-0.2.8.tar.gz	397.9 kB	Aug 26, 2026	Details

Built distribution (wheel)

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

Total release size: 550.8 kB

Release files / cli_agent_runner-0.2.8.tar.gz

Download URL	cli_agent_runner-0.2.8.tar.gz
Size	397.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`57c607839b08f617da31d0bca1c3a7e02b9fcdbf43223b6ca270b6db2354ea76`
BLAKE2b-256 checksum How to use checksums	`35477b66600a0b7337555132b934fb0396958b099623543d8e561c57db72938d`
Upload date	Aug 26, 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/81c900ab4cf22319f78a6b8cac352235cf741dea

Workflow

Publishing configuration: github.com/wan9yu/cli-agent-runner/blob/81c900ab4cf22319f78a6b8cac352235cf741dea/.github/workflows/release.yml
Publishing logs: github.com/wan9yu/cli-agent-runner/actions/runs/32920987528/attempts/1

Artifact

Subject: cli_agent_runner-0.2.8.tar.gz
SHA-256 checksum: 57c607839b08f617da31d0bca1c3a7e02b9fcdbf43223b6ca270b6db2354ea76 Verifying attestations

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

Download URL	cli_agent_runner-0.2.8-py3-none-any.whl
Size	152.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b6570c0ffbae72fc0a06ebba96e31c902873e8c8f9e331e2350fff2060957048`
BLAKE2b-256 checksum How to use checksums	`61094d6f5004915f29cb7922ab7a8b1d25076da32cd2a4aac642c6a095045332`
Upload date	Aug 26, 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/81c900ab4cf22319f78a6b8cac352235cf741dea

Workflow

Publishing configuration: github.com/wan9yu/cli-agent-runner/blob/81c900ab4cf22319f78a6b8cac352235cf741dea/.github/workflows/release.yml
Publishing logs: github.com/wan9yu/cli-agent-runner/actions/runs/32920987528/attempts/1

Artifact

Subject: cli_agent_runner-0.2.8-py3-none-any.whl
SHA-256 checksum: b6570c0ffbae72fc0a06ebba96e31c902873e8c8f9e331e2350fff2060957048 Verifying attestations