codex-autorunner 1.0.0

Codex autorunner CLI per DESIGN-V1

codex-autorunner

An opinionated autorunner that uses the Codex app-server as the primary execution backend with OpenCode support to work on large tasks via a simple loop. On each loop we feed the Codex instance the last one's final output along with core documents.

In the current model, the primary work surface is tickets:

• .codex-autorunner/tickets/TICKET-###.md

Optionally, you can maintain lightweight workspace docs (auto-created on write; missing is OK):

• .codex-autorunner/workspace/active_context.md
• .codex-autorunner/workspace/decisions.md
• .codex-autorunner/workspace/spec.md

Sneak Peak

Run multiple agents on many repositories, with git worktree support

See the progress of your long running tasks with a high level overview

Dive deep into specific agent execution with a rich but readable log

Tickets and workspace docs are markdown files. Edit them directly or use the web UI’s file chat to iterate with the agent.

Use codex CLI directly for multi-shot problem solving or /review

Mobile-first experience, code on the go with Whisper support (BYOK)

What it does

• Initializes a repo with Codex-friendly docs and config.
• Runs Codex app-server in a loop against the repo, streaming logs via OpenCode runtime.
• Tracks state, logs, and config under .codex-autorunner/.
• Exposes a power-user HTTP API and web UI for tickets, workspace docs, file chat, logs, runner control, and a Codex TUI terminal.
• Optionally runs a Telegram bot for interactive, user-in-the-loop Codex sessions.

CLI commands are available as codex-autorunner or the shorter car.

Install

PyPI (pipx):

pipx install codex-autorunner

GitHub (pipx, dev):

pipx install git+https://github.com/Git-on-my-level/codex-autorunner.git

From source (editable):

git clone https://github.com/Git-on-my-level/codex-autorunner.git
cd codex-autorunner
pip install -e .

Optional extras

• Telegram bot support: pip install codex-autorunner[telegram]
• Voice transcription support: pip install codex-autorunner[voice]
• Dev tools (lint/test): pip install codex-autorunner[dev]
• Local dev alternative: pip install -e .[extra]

Dev setup

• make setup creates .venv, installs .[dev], runs pnpm install, and sets core.hooksPath to .githooks.

Opinionated setup (macOS headless hub at ~/car-workspace)

• One-shot setup (user scope): scripts/install-local-mac-hub.sh. It pipx-installs this repo, creates/initializes ~/car-workspace as a hub, writes a launchd agent plist, and loads it. Defaults: host 127.0.0.1, port 4173, label com.codex.autorunner. Override via env (WORKSPACE, HOST, PORT, LABEL, PLIST_PATH, PACKAGE_SRC). For remote access, prefer a VPN like Tailscale and keep the hub bound to loopback; if you bind to a non-loopback host, the script configures server.auth_token_env + a token in .codex-autorunner/.env.
• Create/update the launchd agent plist and (re)load it: scripts/launchd-hub.sh (or make launchd-hub).
• Linux users: see docs/ops/systemd.md for systemd hub/Telegram setup.
• Manual path if you prefer:
  • pipx install .
  • car init --mode hub --path ~/car-workspace
  • Copy docs/ops/launchd-hub-example.plist to ~/Library/LaunchAgents/com.codex.autorunner.plist, replace /Users/you with your home, adjust host/port if desired, then launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist.
• The hub serves the UI/API from http://<host>:<port> and writes logs to ~/car-workspace/.codex-autorunner/codex-autorunner-hub.log. Each repo under ~/car-workspace should be a git repo with its own .codex-autorunner/ (run car init in each).

Refresh a launchd hub to the current branch

When you change code in this repo and want the launchd-managed hub to run it:

1. Recommended: run the safe refresher, which installs into a new venv, flips ~/.local/pipx/venvs/codex-autorunner.current, restarts launchd, health-checks, and auto-rolls back on failure:

make refresh-launchd

Important: avoid in-place pip/pipx installs against the live venv. During uninstall/reinstall, packaged static assets disappear and the UI can break while the server keeps running. Use the safe refresher or stop the service before manual installs.

2. Manual path (offline only; no rollback): stop launchd first, then reinstall into the launchd venv (pipx default paths shown; adjust if your label/paths differ):

$HOME/.local/pipx/venvs/codex-autorunner/bin/python -m pip install --force-reinstall /path/to/your/codex-autorunner

3. Restart the agent so it picks up the new bits (default label is com.codex.autorunner; default plist ~/Library/LaunchAgents/com.codex.autorunner.plist):

launchctl unload ~/Library/LaunchAgents/com.codex.autorunner.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist
launchctl kickstart -k gui/$(id -u)/com.codex.autorunner

4. Tail the hub log to confirm it booted: tail -n 50 ~/car-workspace/.codex-autorunner/codex-autorunner-hub.log.

Health checks (recommended)

• GET /health returns 200 (verifies static assets are present).
• GET /static/app.js returns 200.
• Optional: GET / returns HTML (not a JSON error). If you set a base path, prefix all checks with it.

Quick start

1. Install (editable): pip install -e .
2. Initialize (hub + repo): codex-autorunner init --git-init (or car init --git-init if you prefer short). This creates the hub config at .codex-autorunner/config.yml, plus state/log files and starter content under .codex-autorunner/ (tickets and optional workspace docs).
3. Run once: codex-autorunner once / car once
4. Continuous loop: codex-autorunner run / car run
5. If stuck: codex-autorunner kill then codex-autorunner resume (or the car equivalents)
6. Check status/logs: codex-autorunner status, codex-autorunner log --tail 200 (or car ...)

Configuration

• Root defaults live in codex-autorunner.yml (committed).
• Local overrides live in codex-autorunner.override.yml (gitignored). Use it for machine-specific tweaks; keep secrets in env vars.
• Hub config lives at .codex-autorunner/config.yml (generated). It includes repo_defaults for all repos.
• Repo overrides are optional; add .codex-autorunner/repo.override.yml to override hub defaults for a specific repo.

Interfaces

CAR supports two interfaces with the same core engine. The web UI is the power user control plane for multi-repo visibility and system control. The Telegram bot is optimized for interactive back-and-forth, mirroring the Codex TUI experience inside Telegram with user-in-the-loop approvals.

Web UI (control plane)

1. Ensure the hub is initialized (codex-autorunner init) so .codex-autorunner/config.yml exists.
2. Start the API/UI backend: codex-autorunner serve (or car serve) — defaults to 127.0.0.1:4173; override via server.host/server.port in .codex-autorunner/config.yml.
3. Open http://127.0.0.1:4173 for the hub UI; repo UIs live under /repos/<repo_id>/. FastAPI endpoints are under /api/* (repo) and /hub/* (hub).
   • The Terminal tab launches the configured Codex binary inside a PTY via websocket; it uses codex.terminal_args (defaults empty, so it runs codex bare unless you override). xterm.js assets are vendored under static/vendor.
   • Repo IDs are URL-safe slugs; if a repo directory or requested ID contains spaces, #, or other unsafe chars, the hub stores the original name as display_name and generates a safe repo_id for URLs.
   • If you need to serve under a proxy prefix (e.g., /car), set server.base_path in .codex-autorunner/config.yml or pass --base-path to car serve/hub serve; all HTTP/WS endpoints will be reachable under that prefix. Proxy must forward that prefix (e.g., Caddy handle /car/* { reverse_proxy ... } with a 404 fallback for everything else).
   • Chat composer shortcuts: desktop uses Cmd+Enter (or Ctrl+Enter) to send and Shift+Enter for newline; mobile uses Enter to send and Shift+Enter for newline.

Telegram bot (interactive sessions)

• The interactive Telegram bot is separate from notifications.telegram (which is one-way notifications).
• Each operator should create their own Telegram bot token. Multi-user use requires explicit allowlists.
• Quickstart:
  1. Set env vars: CAR_TELEGRAM_BOT_TOKEN (and optionally CAR_TELEGRAM_CHAT_ID).
  2. In config, set telegram_bot.enabled: true and fill allowed_user_ids + allowed_chat_ids.
  3. Run car telegram start --path <repo_or_hub>.
  4. Use /bind (hub mode) and /new or /resume in Telegram.
• How it works (high level):
  • The bot polls the Telegram Bot API, allowlists chat/user IDs, and routes each topic to a workspace + Codex thread.
  • Messages and media are forwarded to the Codex app-server, streaming responses back to Telegram.
  • Approvals can be requested inline, giving a hands-on, TUI-like workflow without leaving Telegram.
• Details: docs/telegram/architecture.md, docs/ops/telegram-bot-runbook.md, and docs/telegram/security.md.

Security and remote access

• The UI/API are effectively privileged access and can execute code on your machine (terminal + runner).
• Keep the server bound to 127.0.0.1 and use Tailscale (or another VPN) for remote access.
• If you must expose it, set server.auth_token_env and also put it behind an auth-enforcing reverse proxy (basic auth/SSO).
• Do not expose it publicly without protections. See docs/web/security.md for details.

Auth token (optional)

If you set server.auth_token_env, the API requires Authorization: Bearer <token> on every request.

• Set the config: server.auth_token_env: CAR_SERVER_TOKEN.
• Export the token before starting the server: export CAR_SERVER_TOKEN="...".
• Browser UI: visit http://host:port/?token=... once. The UI stores it in sessionStorage and removes it from the URL; WebSocket connections send the token via Sec-WebSocket-Protocol: car-token-b64.<base64url(token)>.
• CLI: requests automatically attach the token from server.auth_token_env; if the env var is missing, CLI commands will error.

Git hooks

• Install dev tools: pip install -e .[dev]
• Point Git to the repo hooks: git config core.hooksPath .githooks
• The pre-commit hook runs scripts/check.sh (Black formatting check + pytest). Run it manually with ./scripts/check.sh before committing or in CI.

Commands (CLI)

• init — seed config/state/docs.
• run / once — run the loop (continuous or single iteration).
• resume — clear stale lock/state and restart; --once for a single run.
• kill — SIGTERM the running loop and mark state error.
• status — show current state.
• sessions — list terminal sessions (server-backed when available).
• stop-session — stop a terminal session by repo (--repo) or id (--session).
• log — view logs (tail or specific run).
• edit — open active_context|decisions|spec in $EDITOR.
• serve — start the HTTP API (FastAPI) on host/port from config (defaults 127.0.0.1:4173).

Star history