codex-autorunner (CAR)

codex-autorunner · Git-on-my-level/codex-autorunner · ★ 809 · last commit 2026-05-26

Ticket-driven background daemon that orchestrates Codex (or any ACP agent) against a work queue, notifying humans via Telegram/Discord only when agents are stuck.

Best whenFilesystem is the only source of truth; agents are executors, not authorities; YOLO by default (danger-full-access) with safety as explicit opt-in — the bitt…

Skip ifCoupling to chat history instead of disk state, Verbose per-run artifacts as default (use compact manifests)

vs seeds

taskmaster-ai(task queue, agent orchestration), but CAR is a full runtime harness (daemon, web UI, Discord/Telegram) rather than a ta…

Primitive shape

No installable primitives

Summary

codex-autorunner (CAR) — Summary

Elevator pitch: A Python-based meta-harness for coding agents (Codex, Hermes, OpenCode, any ACP-compatible agent) that implements a ticket-driven state machine: "Plan once, then let your favorite coding agents grind through tickets while you sleep — and ping you on Telegram or Discord when they're stuck." Users write or generate markdown tickets (with YAML frontmatter), CAR works through the queue autonomously, and notifies via Telegram or Discord only when human input is needed. CAR is agent-agnostic — it does not do any coding itself; it provides scheduling, state management, and notification surfaces for agents that do. Codex is the primary supported backend but is replaceable with Hermes, OpenCode, or any ACP runtime. The architecture is explicitly 4-layered (Engine, Control Plane, Adapters, Surfaces) with a SQLite-backed orchestration store, a web UI (Svelte), a FastAPI server, a Typer CLI, and Discord/Telegram bots. Compared to seeds: most similar to taskmaster-ai (ticket/task queue, agent orchestration) but differs by being a full runtime harness (not just a task planner), supporting multiple agent backends, and using filesystem tickets as the control plane rather than a single tasks.json.

Overview

codex-autorunner (CAR) — Overview

Origin

By Git-on-my-level. Version 2.0.0. MIT license. 809 stars, 70 forks. Active: last commit 2026-05-26 (today — most actively developed in this batch). 7 contributors. Published to PyPI: pip install codex-autorunner / pipx install codex-autorunner.

Philosophy (verbatim from README)

"CAR is very bitter-lesson-pilled. As models and agents get stronger, CAR should serve as leverage and stay out of their way. We treat the filesystem as the first-class data plane and lean on tools agents already know cold (git, python, markdown)."

"Because tickets are the control plane and agents are the execution layer, CAR is an amplifier. With a strong model it sings; with a model that scope-creeps or reward-hacks (marks tickets done that aren't), it will not."

Codebase Constitution (10 non-negotiable invariants, verbatim)

"Filesystem is the source of truth"
"Canonical runtime state lives under a single root" (.codex-autorunner/)
"Layering and replaceability" (Engine/Control Plane/Adapters/Surfaces)
"YOLO by default; safety is an opt-in posture" (full permissions default)
"Determinism over cleverness"
"Small, reviewable diffs"
"Observability is a contract"
"CAR is self-describing" (car describe --json)
"Ticket templates are first-class control plane"
"Agents are executors, not authorities"

Supported Agent Backends

Codex (primary): via codex app-server or codex exec --yolo --sandbox danger-full-access
Hermes (recommended PMA): via ACP protocol, has global memory
OpenCode: ACP backend
Any ACP-compatible agent

Architecture

codex-autorunner — Architecture

Distribution

Type: Python CLI tool + web app
Binary: car
Version: 2.0.0
License: MIT
PyPI: codex-autorunner

Install

pipx install codex-autorunner  # or: pip install codex-autorunner
car --version
mkdir ~/car-hub && cd ~/car-hub
car init --mode hub

Required Runtime

Python >= 3.10
Codex CLI (or Hermes, OpenCode, other ACP agent)
Optional: Telegram bot token, Discord bot token

Technology Stack

Layer	Technology
CLI surface	Typer (Python)
Web surface	FastAPI + Svelte frontend
Engine	Python state machine
Orchestration DB	SQLite (`orchestration.sqlite3`)
Per-repo state	SQLite (`state.sqlite3`, `flows.db`)
Notifications	Telegram bot, Discord bot

4-Layer Architecture

Surfaces (Web UI, CLI, Discord, Telegram, ACP Remote)
    ↓ one-way
Adapters (GitHub, Telegram, App Server)
    ↓ one-way
Control Plane (.codex-autorunner/ filesystem + tickets)
    ↓ one-way
Engine (core state machine, flow runner)

Data Layout

~/car-hub/                          # Hub root
├── codex-autorunner.yml            # Defaults (committed)
├── codex-autorunner.override.yml   # Local overrides (gitignored)
├── .codex-autorunner/
│   ├── manifest.yml                # Managed repos
│   ├── hub_state.json
│   ├── config.yml
│   ├── orchestration.sqlite3       # Orchestration metadata
│   └── templates/                  # Hub-scoped ticket templates
└── repos/
    └── <repo>/
        └── .codex-autorunner/
            ├── tickets/             # TICKET-###.md (control plane)
            ├── contextspace/
            │   ├── active_context.md
            │   ├── decisions.md
            │   └── spec.md
            ├── config.yml
            ├── state.sqlite3
            ├── flows.db             # Flow engine state
            └── discord_state.sqlite3, telegram_state.sqlite3

Target Agent Backends

Codex (via codex app-server or codex exec)
Hermes (via ACP)
OpenCode (via ACP)
Any ACP-compatible agent

Components

codex-autorunner — Components

CLI Binary (`car`) Subcommands

Subcommand	Purpose
`car init --mode hub`	Initialize a hub directory
`car init --mode repo`	Initialize per-repo CAR state
`car run`	Start the autorunner loop (work the ticket queue)
`car run --stop-after-runs N`	Run N tickets then stop
`car ticket new`	Create a new ticket interactively
`car ticket list`	List tickets and status
`car describe --json`	Machine-readable self-description (agent-introspection)
`car web`	Start the web UI + FastAPI server
`car chat`	Start PMA (Project Manager Agent) chat

Web UI (Svelte + FastAPI)

Key capabilities:

Hub and repo management
Ticket create/edit/assign/status view
Agent session chat (PMA interface)
Automation run log
Usage metrics

Notification Surfaces

Surface	When to Use
Telegram bot	Persistent multi-device chat, no internet exposure needed
Discord bot	Team-based collaboration interface
Web UI	Primary control plane
CLI	Agent-friendly surface

Ticket System

Tickets are markdown files with YAML frontmatter under .codex-autorunner/tickets/TICKET-###.md:

Ticket templates in .codex-autorunner/templates/ (hub-scoped) or contributed to car-ticket-templates repo
Tickets can generate child tickets, spawn subagent code reviews, etc.

Contextspace

Per-repo documentation injected into every agent run:

active_context.md — current project state
decisions.md — architectural decision log
spec.md — project specification

Agent Adapters

Adapter	Protocol
Codex	`codex app-server` JSON-RPC or `codex exec --yolo`
Hermes	ACP (Agent Client Protocol)
OpenCode	ACP
GitHub	SCM automation (PR creation, etc.)

SQLite Databases

Database	Location	Purpose
`orchestration.sqlite3`	Hub	Orchestration metadata, bindings, executions, transcript mirrors
`state.sqlite3`	Per-repo	Per-repo run state
`flows.db`	Per-repo	Flow engine state (pause/resume/restart history)
`discord_state.sqlite3`	Per-repo	Discord delivery/outbox state
`telegram_state.sqlite3`	Per-repo	Telegram delivery/outbox state

Prompts

codex-autorunner — Prompts

Prompt 1: Codebase Constitution — Agent Role Definition (verbatim)

Source: docs/car_constitution/10_CODEBASE_CONSTITUTION.md

### 10) Agents are executors, not authorities
- Agents propose and execute; files decide.
- No hidden coupling to chat history; re-load truth from disk each run.

Prompting technique: Agent role boundaries via constitution. The constitution defines the agent's epistemological status — agents propose, but the filesystem decides. This prevents agents from treating prior session memory as authoritative.

Prompt 2: Codebase Constitution — Observability Contract (verbatim)

Source: docs/car_constitution/10_CODEBASE_CONSTITUTION.md

### 7) Observability is a contract
- Every run must leave enough signal to answer: what happened, why, where it failed.
- A run that cannot be explained from artifacts is considered a failed run.
- Observability must be bounded and cheap by default: prefer compact manifests and pointers over copied blobs.
- Verbose artifacts are opt-in or retention-bounded, never an unconditional per-invocation default.

Prompting technique: Failure-definition by observability. Redefining "run failure" to include "run that cannot be explained from artifacts" is a prompting strategy that makes observability a first-class success criterion rather than an afterthought.

Prompt 3: YOLO Default Configuration (verbatim from codex-autorunner.yml)

codex:
  args:
    - --yolo
    - exec
    - --sandbox
    - danger-full-access
  # NOTE: --sandbox danger-full-access is powerful; change only if you understand the tradeoffs.

Prompting technique: Opinionated defaults with explicit warning. The default sandbox mode is danger-full-access — this is a design decision, not an oversight. The comment acknowledges the risk and defers the safety decision to the user, which is consistent with the "bitter-lesson-pilled" philosophy.

Uniqueness

codex-autorunner — Uniqueness

differs_from_seeds

The closest seed is taskmaster-ai (task queue, agent orchestration, file-based state). However, CAR differs in several fundamental ways: it is a full runtime harness (daemon process, web UI, Discord/Telegram bots) rather than a task manager; it is explicitly agent-agnostic (Codex, Hermes, OpenCode, any ACP backend) rather than model-specific; it uses filesystem tickets as the control plane (markdown files with YAML frontmatter) rather than a single tasks.json; and it includes a formal 4-layer architecture (Engine/Control Plane/Adapters/Surfaces) with 10 constitutional invariants. The "bitter-lesson-pilled" philosophy (filesystem > chat history > model memory; agents are executors, not authorities) is the sharpest philosophical contrast with prompt-engineering-heavy frameworks like superpowers or BMAD-METHOD.

The "Tickets as Code" Philosophy

"Tickets aren't just task descriptions — they're a software layer that operates inside CAR. You can write tickets that scope a feature and generate child tickets, spawn subagent code reviews, repay tech debt, etc."

This treats tickets as executable programs in a domain-specific language, not just work items.

Most Unusual Features

car describe --json: Machine-readable self-description (constitution invariant #8) — CAR describes itself to agents so they can understand how to interact with it without relying on prior chat history.
Constitutional governance: 10 formal non-negotiable invariants governing code evolution — no other framework in this batch has a constitution with explicit invariants.
PMA (Project Manager Agent): A separate conversational AI (Hermes recommended) that manages CAR itself — a meta-agent layer on top of the execution agents.
YOLO-by-default: Full filesystem + network permissions (--sandbox danger-full-access) as the default posture, with safety as explicit opt-in.

Observable Failure Modes

Reward hacking: Agents that mark tickets done without completing the work will not be caught. The constitution acknowledges: "With a model that scope-creeps or reward-hacks (marks tickets done that aren't), it will not" sing.
Constitutional drift: The 10 invariants are documented but not enforced programmatically. Over time, implementation may diverge.
Multi-repo isolation: Running agents against multiple repos simultaneously with full permissions is high-risk if worktree isolation is not configured.
Dependency on ACP: As newer agent protocols emerge, CAR's ACP adapter layer may require updates to stay compatible.

Workflow

codex-autorunner — Workflow

Core Execution Loop

while incomplete tickets exist:
    1. Select Ticket: pick active ticket from .codex-autorunner/tickets/
    2. Build Prompt: from ticket content + contextspace docs + bounded prior run output
    3. Run: execute configured backend (Codex/Hermes/OpenCode)
    4. Update State: check stop rules (exit code, stop_after_runs, limits)
    5. Notify: if stuck → ping user on Telegram/Discord

Ticket Lifecycle

TICKET-###.md created (by user, agent, or CAR template)
    ↓
Status: pending → in_progress (agent picks it up)
    ↓
Agent runs on ticket
    ↓
Status: done (agent marks) or blocked (needs human input)
    ↓ (if blocked)
Notification to Telegram/Discord
    ↓
Human reviews/unblocks
    ↓ (if done)
Next ticket selected

Phases + Artifacts

Phase	Artifact
Hub Init	`codex-autorunner.yml`, `manifest.yml`
Repo Init	`.codex-autorunner/config.yml`, `tickets/` dir
Ticket Creation	`TICKET-###.md` (markdown + YAML frontmatter)
Agent Run	Run log in `state.sqlite3` + notification if blocked
SCM Automation	PR created via GitHub adapter (optional)

Stop Rules

stop_after_runs: N — stop after N ticket runs
max_wallclock_seconds — hard time limit
Exit code from agent — non-zero triggers state update
User notification threshold — human input required

Approval Gates

Gate	Type	Mechanism
Human input required	`freetext-clarify`	Telegram/Discord notification
Ticket assignment	manual	User assigns via web UI or CLI
Commit review (optional review flow)	`file-review`	Review subagent spawned by ticket

YOLO Mode

Default execution posture: codex exec --yolo --sandbox danger-full-access. This is full filesystem + network access. The constitution (invariant #4) states: "Safety knobs exist as explicit modes for higher-stakes contexts."

Memory Context

codex-autorunner — Memory and Context

State Storage

Store	Location	Contents
Ticket queue	`.codex-autorunner/tickets/TICKET-###.md`	Work items (markdown + YAML frontmatter)
Contextspace	`.codex-autorunner/contextspace/`	`active_context.md`, `decisions.md`, `spec.md`
Run history	`.codex-autorunner/state.sqlite3`	Per-run state, exit codes, outputs
Flow state	`.codex-autorunner/flows.db`	Flow engine: pause/resume/restart history
Orchestration	Hub `orchestration.sqlite3`	Thread targets, executions, bindings, chat events
Transport state	`discord_state.sqlite3`, `telegram_state.sqlite3`	Delivery/outbox queues

Prompt Construction

Each agent run receives:

CAR self-knowledge (ticket format, contextspace structure)
Contextspace docs (active_context.md, decisions.md, spec.md)
Current ticket content
Bounded prior run output (configurable: prev_run_max_chars: 6000)

The prev_run_max_chars limit prevents unbounded context growth across long-running queues.

Persistence

Global: ~/.codex-autorunner/ — update cache, shared app-server workspaces
Hub: ~/car-hub/.codex-autorunner/ — manifest, orchestration
Per-repo: .codex-autorunner/ under each managed repo — canonical per-repo state

Filesystem as Source of Truth

Constitution invariant #1: "Durable artifacts > chat transcripts > model memory. If something matters (state, decisions, outputs), it must be representable on disk." Every run reloads state from disk; no implicit chat history coupling.

Cross-Session Handoff

Fully supported — tickets persist across agent restarts. The flows.db tracks pause/resume/restart history. Agent restarts pick up from the last ticket state.

Compaction

prev_run_max_chars limits prior run output injected into each prompt. Verbose artifacts are opt-in (constitution invariant #7).

Orchestration

codex-autorunner — Orchestration

Multi-Agent

Yes — CAR supports running agents against multiple repos/worktrees simultaneously (hub mode). Each repo has its own agent process and ticket queue.

Orchestration Pattern

Continuous-loop (not event-driven). The autorunner is a background daemon that continuously works through the ticket queue until stopped. "While incomplete tickets exist" is the termination condition.

Isolation Mechanism

Container (optional): Docker runtime per repo/worktree is documented and recommended for isolated execution. Git worktree per feature is natively supported.

Codex Role

Worker — primary execution backend. Codex receives the prompt (ticket + context) and executes. CAR does not give Codex a planner, reviewer, or auditor role — those capabilities must be encoded in the tickets themselves (a ticket can spawn a review subagent, for example).

Multi-Model

No — CAR is backend-agnostic. It routes all work to one configured backend (Codex, Hermes, or OpenCode) per repo. Multiple backends can run in different repos under the same hub.

Execution Mode

Background daemon / scheduled. The car run command runs the execution loop in the foreground; in practice it's designed to run unattended ("walk away, agents work the queue").

Agent Protocol

ACP (Agent Client Protocol) — enables integration with any ACP-compatible agent. Codex adapter uses codex app-server JSON-RPC; Hermes and OpenCode use ACP protocol.

Consensus Mechanism

None. Tickets are sequential; no multi-agent consensus. Review tickets can spawn a separate review subagent, but this is user-designed ticket logic, not CAR's built-in behavior.

Project Manager Agent (PMA)

An optional conversational interface to CAR itself. Hermes is recommended as PMA due to its global memory. The PMA helps create tickets, query status, and provide context — it's a CAR meta-agent, not a coding agent.

Ui Cli Surface

codex-autorunner — UI and CLI Surface

Dedicated CLI Binary

Yes — car binary (Python Typer app).

Subcommand Group	Key Commands
Hub management	`car init --mode hub`, `car web`
Repo management	`car init --mode repo`, `car run`
Ticket management	`car ticket new`, `car ticket list`
Agent interaction	`car chat` (PMA)
Introspection	`car describe --json`

Local Web UI

Yes — Svelte frontend + FastAPI backend.

Property	Value
Type	Web dashboard
Port	Configurable (default unknown from public docs)
Tech stack	Svelte + FastAPI (Python)
Features	Ticket management, agent chat (PMA), automation runs, git status, usage metrics

Notification Surfaces

Surface	Protocol	Use Case
Telegram	Bot API	Persistent multi-device chat
Discord	Bot API	Team-based notification and chat

Remote Control

When running in web mode, the FastAPI server enables:

HTTP API for all hub and repo operations
WebSocket stream for real-time agent output
Remote scripting and CI/CD integration

P2P

Not present in CAR (this is a Codexia feature).

Observability

Every run produces artifacts in state.sqlite3
car describe --json is a machine-readable self-description endpoint (constitution invariant #8)
Run logs in per-repo .codex-autorunner/ directory
Transcript mirrors in orchestration.sqlite3 for chat visibility

Cross-Tool Portability

High — CAR works with Codex, Hermes, OpenCode, and any ACP agent. The frontend control plane (web UI, CLI, Discord, Telegram) is independent of the execution backend.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k

A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k

A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k

A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k

A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k

A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k

A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…

Distribution

Type: cli-tool
License: MIT
Install: multi-step
Version: 2.0.0

Surfaces

CLI binary: car
CLI subcmds: 10
Local UI: web-dashboard
Tech stack: Svelte frontend + FastAPI (Python) backend

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 0
Templates: 5

Workflow

Phases: 6
Approval gates: 2
Spec format: markdown
Spec storage: per-feature-folder
Delta or full: whole-file

Orchestration

Multi-agent: Yes
Pattern: continuous-ralph
Isolation: container
Consensus: none
Prompt chaining: No

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: background-daemon
Crash recovery: Yes
Compaction: Yes
Session handoff: Yes
Streaming: Yes

Memory

Type: sqlite
Persistence: project
Search: none
State files: 7 files

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: Yes
Auto PR: Yes
Auto merge: No
Worktree/feat: Yes
Audit log: Yes
Audit format: sqlite
Replay: Yes

Tools

Primary: openai-codex
Targets: 3
Portability: high

Signals

Stars: 809
Last commit: 2026-05-26
Contributors: 7
Maintainer: active
Quality score: 6/10

Summary

codex-autorunner (CAR) — Summary

Overview

codex-autorunner (CAR) — Overview

Origin

Philosophy (verbatim from README)

Codebase Constitution (10 non-negotiable invariants, verbatim)

Supported Agent Backends

Architecture

codex-autorunner — Architecture

Distribution

Install

Required Runtime

Technology Stack

4-Layer Architecture

Data Layout

Target Agent Backends

Components

codex-autorunner — Components

CLI Binary (car) Subcommands

Web UI (Svelte + FastAPI)

Notification Surfaces

Ticket System

Contextspace

Agent Adapters

SQLite Databases

Prompts

codex-autorunner — Prompts

Prompt 1: Codebase Constitution — Agent Role Definition (verbatim)

Prompt 2: Codebase Constitution — Observability Contract (verbatim)

Prompt 3: YOLO Default Configuration (verbatim from codex-autorunner.yml)

Uniqueness

codex-autorunner — Uniqueness

differs_from_seeds

The "Tickets as Code" Philosophy

Most Unusual Features

Observable Failure Modes

Workflow

codex-autorunner — Workflow

Core Execution Loop

Ticket Lifecycle

Phases + Artifacts

Stop Rules

Approval Gates

YOLO Mode

Memory Context

codex-autorunner — Memory and Context

State Storage

Prompt Construction

Persistence

Filesystem as Source of Truth

Cross-Session Handoff

Compaction

Orchestration

codex-autorunner — Orchestration

Multi-Agent

Orchestration Pattern

Isolation Mechanism

Codex Role

Multi-Model

Execution Mode

Agent Protocol

Consensus Mechanism

Project Manager Agent (PMA)

Ui Cli Surface

codex-autorunner — UI and CLI Surface

Dedicated CLI Binary

Local Web UI

Notification Surfaces

Remote Control

P2P

Observability

Cross-Tool Portability

Related frameworks

CLI Binary (`car`) Subcommands