The Problem
Running long-horizon coding agent workflows (Codex, OpenCode, Hermes) manually is tedious and error-prone. You write a plan, then babysit each agent turn, re-prompting when the agent stalls or needs clarification. This repo, codex-autorunner (CAR), solves that by acting as a meta-harness: you write tickets once, agents grind through them autonomously, and CAR pings you on Telegram or Discord only when human input is required.
What This Does
CAR is a state machine, not a coding agent. It coordinates agents that speak the Agent Client Protocol (ACP). The core loop: while tickets remain, pick the next one, hand it to an agent with a pre-built contextspace, and optionally pass the previous agent's output. Tickets are markdown files with frontmatter, stored on the filesystem—the control plane is plain text, not a database.
The entry point is src/codexautorunner/main.py, which exposes a CLI (car) and a web UI. The apps/autooptimize/ directory contains a self-improvement loop that records baselines, plans next tickets, and renders summary cards. The scripts/ folder (47 files) is heavy on validation and drift detection—checkimportboundaries.py, checkprotocoldrift.py, and checkdestinationcontractdrift.py suggest a strong emphasis on keeping the system honest as agents evolve.
How To Use It
Setup is documented in two paths: let an agent walk you through docs/AGENTSETUPGUIDE.md, or install manually.
pipx install codex-autorunner # or: pip install codex-autorunner car --version mkdir ~/car-hub && cd ~/car-hub car init --mode hub
Then open the web UI, add a repo, and write tickets. Configuration lives in codex-autorunner.yml and .env.example. The Makefile and pyproject.toml confirm a Python package; package.json and pnpm-lock.yaml indicate a frontend (likely the web UI). CI is via GitHub Actions (.github/workflows/ci.yml, release.yml, codeql.yml). For chat surfaces, follow docs/AGENTSETUPTELEGRAMGUIDE.md or docs/AGENTSETUPDISCORDGUIDE.md. Docker runtime per repo is covered in docs/configuration/destinations.md.
Real-World Use
A typical workflow: you write a plan for "refactor the auth module and add rate limiting." You convert it to tickets using the CAR Ticket Skill (docs/car-ticket-skill.md). CAR dispatches ticket #1 to Codex, which edits files in a worktree. When done, CAR runs validation scripts (the scripts/check*.py suite) and either passes the output to the next agent or flags a failure. If an agent marks a ticket done without passing validation, CAR catches it—the repo's philosophy explicitly warns against agents that "reward-hack." You get a Telegram message only when the queue stalls.
Code Health & Issues
The repo is unusually disciplined for a solo project. Tests exist (5 files), CI is configured, CodeQL and Dependabot are active, and there's a LICENSE. The docs/carconstitution/ folder is a full engineering standards document. Med - The scripts/ folder has 47 files, many doing one-off validation. This suggests tooling sprawl and potential maintenance burden. Several (idlecpusoak.py, chatsurfaceseeded_exploration.py) look like operational experiments, not production code. Low - A car file at the repo root (no extension) is unusual; likely an artifact or a stray binary. Verify it's not committed by accident. Low - The README's "bitter-lesson-pilled" tone and heavy dependency on agent discipline means outcomes vary wildly with model quality. The repo admits this.
The Bottom Line
CAR is a serious, well-engineered tool for developers who run multi-hour agent workflows and want a hands-off orchestration layer. The filesystem-as-data-plane design is pragmatic and auditable. It's not for beginners—setup requires comfort with CLIs, worktrees, and agent quirks. If you're running long-horizon coding agents solo, this is worth a look. If you babysit every turn, you don't need it yet.