Codex Autopilot Kit

English · Español

# Codex Autopilot Kit

Keep Codex. Add Autopilot.
Turn an existing Codex project into a safe, project-scoped multi-agent workflow.

CI npm License: MIT Zero runtime dependencies

Codex Autopilot Kit installs a tested `.codex/` agent stack plus reusable Goal templates into an existing repository. A supervisor plans and evaluates while scoped subagents explore, implement, test, and independently review. It is deliberately **not another coding agent, IDE, cloud platform, or orchestration runtime**. It is a lightweight autopilot layer for people who already use Codex and want more autonomy without replacing their workflow. > Default strategy: **Supervisor (you choose) → Luna Medium explorer → Luna High worker → Luna High reviewer**, concurrency 1 by default. ## Visual Configurator Configure the stack without memorizing flags: **https://crunaldo.github.io/codex-autopilot-kit/** Choose a Goal preset, execution profile, and maximum subagent concurrency. The configurator shows the resulting roles, reasoning levels, relative model usage, managed files, and exact preview/install commands. Its URL preserves the configuration for sharing. The configurator is static and client-side. It does not receive repository contents or credentials. ## Quick start From the target project root: ```bash npx --yes codex-autopilot-kit init --target . ``` Or preview a fully specified configuration before writing anything: ```bash npx --yes codex-autopilot-kit init \ --target . \ --preset generic \ --profile balanced \ --concurrency 1 \ --yes \ --dry-run ``` Then install: ```bash npx --yes codex-autopilot-kit init \ --target . \ --preset generic \ --profile balanced \ --concurrency 1 \ --yes ``` GitHub remains the canonical source and can be used directly as a fallback: ```bash npx --yes github:crunaldo/codex-autopilot-kit init --target . ``` ## What it installs ```text .codex/ config.toml agents/ explorer.toml worker.toml reviewer.toml autopilot-kit.json AUTOPILOT-GOAL.md ``` Managed conflicts are backed up before replacement. For existing project TOML, `--config-strategy merge` preserves unrelated settings and aborts before writing if kit-owned values conflict. A matching reinstall is idempotent and creates no unnecessary backups. ## Inspect before installing Dry run: ```bash npx --yes codex-autopilot-kit install \ --target . \ --profile balanced \ --preset generic \ --concurrency 1 \ --dry-run ``` Exact diff: ```bash npx --yes codex-autopilot-kit diff --target . ``` Machine-readable diff: ```bash npx --yes codex-autopilot-kit diff --target . --json ``` The preview classifies managed paths as `CREATE`, `REPLACE`, `MERGE`, `CONFLICT`, or `UNCHANGED`, and reports `.gitignore` updates separately. `--dry-run` and `diff` do not write files. ## Verify ```bash npx --yes codex-autopilot-kit doctor --target . ``` For CI and agents: ```bash npx --yes codex-autopilot-kit doctor --target . --json npx --yes codex-autopilot-kit status --target . --json ``` Doctor validates required files, strict UTF-8, role registration, expected models, read-only Explorer/Reviewer, disabled nested agents, concurrency, and the local manifest. ## Architecture

Codex Autopilot Kit architecture

- **Supervisor** — planning, delegation, evaluation, escalation, and stopping decisions. - **Explorer** — targeted read-only discovery. - **Worker** — implementation, debugging, testing, and validation. - **Reviewer** — independent read-only final review. The supervisor model is selected by the user; the kit configures the project-local subagent roles. ## Profiles | Profile | Explorer | Worker | Reviewer | Recommended for | |---|---:|---:|---:|---| | `economy` | medium | medium | high | repetitive or well-scoped work | | `balanced` | medium | high | high | **default; real project work** | | `quality` | high | high | high | difficult, discovery-heavy repositories | No profile enables maximum reasoning automatically. ## Goal presets - `generic` — general software tasks. - `frontend-visual` — DISCOVER → EVIDENCE → BUILD → CAPTURE → COMPARE → FIX → VERIFY. - `backend` — inspect → implement → unit/integration tests → contract checks → review. ## Commands ```text codex-autopilot init Interactive configuration and installation wizard codex-autopilot install Install/update the project-scoped stack codex-autopilot diff Compare current managed files with desired state codex-autopilot doctor Validate files, roles, concurrency, and manifest codex-autopilot status Show installed profile/preset/concurrency/version codex-autopilot presets List available Goal presets codex-autopilot record Save a local run receipt codex-autopilot runs List local receipts codex-autopilot readiness Score observable project readiness codex-autopilot benchmarks Summarize paired benchmark receipts codex-autopilot uninstall Remove managed files; optionally restore backup codex-autopilot print-goal Print a Goal preset to stdout ``` ## Local run receipts and readiness After a Goal, record its outcome and manually observed role counts. The command writes one JSON file under .autopilot/runs/; it does not capture Goal text, tokens, file paths, or send data over the network. ~~~bash npx --yes codex-autopilot-kit record --target . --preset frontend-visual --profile balanced --explorer-calls 1 --worker-calls 3 --reviewer-calls 1 --result PASS --tests PASS --duration-seconds 510 --files-changed 4 npx --yes codex-autopilot-kit runs --target . --json npx --yes codex-autopilot-kit readiness --target . --json ~~~ Readiness is a transparent checklist based on files and Git state, not a measure of model intelligence or a guarantee of task quality. Benchmark comparisons require matching case and pair IDs, the same preset/profile, and one receipt per mode; the summary is descriptive and makes no causal claim. The repository includes three fixed starter tasks in [the benchmark suite](benchmarks/README.md). See also [Telemetry](docs/TELEMETRY.md) and [Benchmark protocol](docs/BENCHMARKS.md). ## Start an autonomous Goal After install/update, open a **new Codex chat** so project-local configuration reloads. Select the supervisor model and use the installed `AUTOPILOT-GOAL.md` contract: ```text /goal Read AUTOPILOT-GOAL.md and autonomously complete the objective below. Respect its roles, safety rules, verification gates, and PASS/BLOCKED contract. Do not wait for me between iterations unless genuinely BLOCKED. OBJECTIVE: ``` ## Safety model The kit is intentionally conservative: - project-local only; - never modifies `~/.codex`; - backups before managed replacement; - no git commit/push; - no package installation in the target project; - no hidden services; - concurrency 1 by default; - Explorer and Reviewer are read-only; - `--dry-run` and `diff` are inspection-only. Read [SAFETY.md](docs/SAFETY.md) before unattended Goals on valuable repositories. ## Documentation - [Visual Configurator](https://crunaldo.github.io/codex-autopilot-kit/) - [Getting started](docs/GETTING_STARTED.md) - [Install for coding agents](INSTALL_FOR_AGENTS.md) - [Architecture](docs/ARCHITECTURE.md) - [Model strategy](docs/MODEL_STRATEGY.md) - [Goal playbook](docs/GOAL_PLAYBOOK.md) - [Telemetry](docs/TELEMETRY.md) - [Benchmark protocol](docs/BENCHMARKS.md) - [Codex compatibility checks](docs/CODEX_COMPATIBILITY.md) - [Safety](docs/SAFETY.md) - [Troubleshooting](docs/TROUBLESHOOTING.md) - [Distribution](docs/DISTRIBUTION.md) - [Roadmap](ROADMAP.md) ## Project status The v1.0.0 release promotes the project-scoped setup and CLI, stable manifest, local run receipts, readiness checks, and benchmark summaries to the stable line. Install the current version from npm with `npm install -g codex-autopilot-kit`. See [CHANGELOG.md](CHANGELOG.md) and [ROADMAP.md](ROADMAP.md) for release details and benchmark limitations. Codex Autopilot Kit is a community project and is not affiliated with or endorsed by OpenAI. Product names and trademarks belong to their respective owners. ## Contributing Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). ## License MIT — see [LICENSE](LICENSE).