Repository git clone https://github.com/moses-y/codex-autorunner

Purpose – CAR (codex‑autorunner) is a meta‑harness that schedules long‑running AI‑agent tickets, persists state in a local “hub”, and notifies via Telegram/Discord. It does not implement an agent; it orchestrates any ACP‑compatible agent (Codex, Hermes, OpenCode, etc.).

1. High‑level Architecture

  • Core orchestration lives under src/codex_autorunner/core/. The most depended‑on modules are:
  • core/utils (79 inbound imports, part of a circular import)
  • core/logging_utils (76 inbound imports, also circular)
  • core/text_utils (74 inbound imports)
  • Hub – src/codex_autorunner/core/hub.py and src/codex_autorunner/core/hub_control_plane/ expose the public API used by the CLI, web UI and agents.
  • Agents – concrete adapters live in src/codex_autorunner/agents/ (e.g., agents/acp/client.py, agents/opencode/supervisor.py).
  • Surfaces – CLI (src/codex_autorunner/cli.py), browser UI (src/codex_autorunner/browser/server.py), and webhook endpoints (src/codex_autorunner/server.py).
  • State & persistence – a SQLite‑backed “state roots” directory (src/codex_autorunner/core/state_roots.py) stores ticket markdown, execution logs and a small DB (≈181 DB‑access functions).
  • External I/O – the code reads/writes files (175 functions), runs external commands (31 functions), makes network calls (13 functions) and performs cryptographic ops (12 functions). The shortest external paths are:
  • start → from_result → session.get (network)
  • main → build_paths → state_dir.mkdir (filesystem)

2. Build / Install

StepCommandEvidence
Install Python depspip install . (or pipx install codex-autorunner)pyproject.toml defines the package.
Install JS toolingpnpm installpackage.json + pnpm-lock.yaml.
Run lint / type checksmake lint (see Makefile)Makefile contains lint target.
Run test suitepytest -q (tests under tests/)825 test files detected.

No Dockerfile is present, so container builds must be added manually if required.

3. Configuration

  • Environment – template at .env.example. Required keys include CAR_HUB_ROOT (path to the hub) and optional TELEGRAM_BOT_TOKEN, DISCORD_WEBHOOK_URL.
  • CLI – car init --mode hub creates the hub directory and writes codex_autorunner/config.yaml.
  • Web UI – launched by the entry point src/codex_autorunner/browser/server.py (start function, line 374). It binds to localhost:8000 by default.

All configuration files are version‑controlled; no secrets are committed.

4. Running the System

# Start the hub (blocks until stopped)
python -m codex_autorunner.browser.server start

# Or run the CLI entry point (useful for scripts)
python -m codex_autorunner.cli run --repo /path/to/repo

The start entry point reaches 232 internal functions and ultimately calls log_event (154 callers) before performing any external I/O.

5. Real‑World Use‑Case

A development team stores a backlog of feature tickets as markdown files under ~/car-hub/tickets. After car init --mode hub, they run car run. The orchestrator picks the first incomplete ticket, invokes the configured Codex agent via the ACP client (agents/acp/client.py), writes the agent’s output back to the ticket, and posts a Telegram message when the ticket stalls. All state lives in the local hub directory; no external service is required unless the team enables the optional webhook surfaces.

6. Code‑Health Findings (static analysis)

SeverityIssueLocation
HighPin third‑party GitHub Actions to commit SHAs.github/workflows/*.yml (e.g., pypa/gh-action-pypi-publish@release/v1)
MediumDeclare least‑privilege permissions for GITHUB_TOKEN.github/workflows/agent-compatibility.yml
MediumAdd a dependency‑vulnerability scan stepany workflow under .github/workflows/
MediumSet persist-credentials: false on actions/checkout.github/workflows/agent-compatibility.yml
LowDefine timeout-minutes for jobs.github/workflows/ci.yml
LowAdd repository convention files (.editorconfig, .gitattributes, formatter config)repo root

Additional measured code issues (not CI‑related):

  • High – 15 import‑cycle members (e.g., core/utils.py, core/logging_utils.py, core/config.py). Breaking the cycles will reduce fragility.
  • High – Deep nesting (max depth 8) in core/state.py, manifest.py, bootstrap.py. Refactor with early returns or helper functions.
  • High – “Hub module” (core/utils.py, core/logging_utils.py, core/text_utils.py) is a blast‑radius hotspot; keep it small and stable.
  • Medium – Files opened without a context manager in three utils modules; wrap with with open(...) as f:.
  • Medium – Broad except: blocks in several integration modules; catch specific exceptions.
  • Medium – Oversized TypeScript file static_src/utils.ts (716 LOC); split by responsibility.

All findings include concrete fix suggestions in the analysis output.

7. Bottom Line

CAR provides a well‑structured, test‑covered orchestration layer for AI‑agent ticket execution, with clear entry points and extensive documentation. The main technical risk is the prevalence of import cycles and a few high‑complexity modules that increase change‑impact; refactoring those will improve maintainability. CI configuration should be hardened by pinning actions, limiting token scope, and adding vulnerability scans. The project is ready for production use by teams comfortable managing local state and secret handling.