Skip to content

README.md

Latest commit

 

History

History
475 lines (322 loc) · 23.9 KB

README.md

File metadata and controls

475 lines (322 loc) · 23.9 KB

Auto-Codex

English | 简体中文

Stars License CI Last Commit Issues

Quick Navigation: What It Does · Key Features · Use Cases · Quick Start · CLI Usage · How It Works · FAQ · llms.txt · 中文

Keywords: OpenAI Codex CLI · autonomous coding agent · multi-agent coding · AI pair programmer · git worktree development · parallel coding agents · spec-driven AI coding · self-validating QA loop · cross-session memory · FalkorDB · Graphiti · Electron desktop · AGPL coding tool

关键词:OpenAI Codex 桌面客户端 · 自主编程代理 · 多代理协作编程 · AI 代码助手 · Git worktree 并行开发 · 规约驱动 AI 编码 · 自验证 QA 循环 · 跨会话记忆 · 本地优先 AI 编程工具 · 开源 AGPL Codex 客户端

Your AI coding companion. Build features, fix bugs, and ship faster — with autonomous agents that plan, code, and validate for you.

Auto-Codex Kanban Board

What It Does

Auto-Codex is a desktop app that supercharges your AI coding workflow. Whether you're a vibe coder just getting started or an experienced developer, Auto-Codex meets you where you are.

Powered by the OpenAI Codex CLI for reliable, sandboxed agent execution.

  • Autonomous Tasks — Describe what you want to build, and agents handle planning, coding, and validation while you focus on other work
  • Agent Terminals — Run Codex CLI in up to 12 terminals with a clean layout, smart naming based on context, and one-click task context injection
  • Safe by Default — All work happens in git worktrees, keeping your main branch undisturbed until you're ready to merge
  • Self-Validating — Built-in QA agents check their own work before you review

The result? 10x your output while maintaining code quality.

Key Features

  • Parallel Agents: Run multiple builds simultaneously while you focus on other work
  • Context Engineering: Agents understand your codebase structure before writing code
  • Self-Validating: Built-in QA loop catches issues before you review
  • Isolated Workspaces: All work happens in git worktrees — your code stays safe
  • AI Merge Resolution: Intelligent conflict resolution when merging back to main — no manual conflict fixing
  • Memory Layer: Agents remember insights across sessions for smarter decisions
  • Cross-Platform: Desktop app runs on Mac, Windows, and Linux
  • Any Project Type: Build web apps, APIs, CLIs — works with any software project

Use Cases

Auto-Codex shines whenever you would otherwise be the bottleneck waiting on a single AI to finish one task at a time. Concrete scenarios:

  • Sprint of independent features — Spin up 4–12 agent terminals, one per feature ticket, and let them run while you review yesterday's batch.
  • Greenfield prototyping — Describe a SaaS / dashboard / API in natural language; Auto-Codex generates a spec, plans subtasks, then implements them in an isolated worktree.
  • Legacy migration — Use the Memory Layer to teach agents your codebase's quirks once, then have them perform large-scale refactors (Vue 2 → Vue 3, JS → TS, Express → Fastify) consistently across files.
  • Bug-fix queue — Paste in a list of GitHub issues; each gets its own spec, branch, and self-QA loop before you review.
  • Solo indie developer scaling — Behave like a small team: pair-program in agent terminals while autonomous tasks build features in the background.
  • OpenAI Codex CLI power user — If you already pay for Codex CLI subscription, Auto-Codex multiplies the value: parallel sessions, persistent memory, spec-driven workflow.
  • CI/CD automation — Run headless via the CLI for nightly refactors, dependency upgrades, or doc generation jobs.

Quick Start (Desktop UI)

The Desktop UI is the recommended way to use Auto-Codex. It provides visual task management, real-time progress tracking, and a Kanban board interface.

Prerequisites

  1. Node.js 18+ - Download Node.js
  2. Python 3.12+ - Download Python
  3. Docker Desktop - Required for the Memory Layer (optional)
  4. Codex CLI - npm install -g @openai/codex
  5. OpenAI Account - Required for Codex CLI access (API key or OAuth token for non-interactive use)
  6. Git Repository - Your project must be initialized as a git repository

Codex CLI Auth (Required)

# Verify install
codex --version

# Interactive login (recommended)
codex login

If you use a third-party gateway/activator that authenticates Codex CLI via API key (commonly stored in ~/.codex/auth.json + ~/.codex/config.toml), Auto-Codex will treat that as authenticated as long as those files are present and valid. Note: GUI-launched apps often do not inherit .zshrc environment variables, so prefer the Codex config files over shell-only exports.

Headless/CI: set one of these instead of interactive login.

# Shell env (one-off)
export OPENAI_API_KEY=sk-...

# Or use an OAuth token from Codex CLI login (e.g. `codex login --device-auth`)
export CODEX_CODE_OAUTH_TOKEN=...

# Or point to an existing Codex CLI config directory
export CODEX_CONFIG_DIR=/path/to/codex/config

# Or rely on the default Codex CLI config at ~/.codex
# (disable with AUTO_CODEX_DISABLE_DEFAULT_CODEX_CONFIG_DIR=1)

# Or add any of the above to auto-codex/.env for repeat usage
OPENAI_API_KEY=sk-...

Git Initialization

Auto-Codex requires a git repository to create isolated worktrees for safe parallel development. If your project isn't a git repo yet:

cd your-project
git init
git add .
git commit -m "Initial commit"

Why git? Auto-Codex uses git branches and worktrees to isolate each task in its own workspace, keeping your main branch clean until you're ready to merge. This allows you to work on multiple features simultaneously without conflicts.

Installing Docker Desktop

Docker runs the FalkorDB database that powers Auto-Codex's cross-session memory.

Operating System Download Link
Mac (Apple Silicon M1/M2/M3/M4) Download for Apple Chip
Mac (Intel) Download for Intel Chip
Windows Download for Windows
Linux Installation Guide

Not sure which Mac? Click the Apple menu (🍎) → "About This Mac". Look for "Chip" - M1/M2/M3/M4 = Apple Silicon, otherwise Intel.

After installing: Open Docker Desktop and wait for the whale icon (🐳) to appear in your menu bar/system tray.

Using the Desktop UI? It automatically detects Docker status and offers one-click FalkorDB setup. No terminal commands needed!

📚 For detailed installation steps, troubleshooting, and advanced configuration, see guides/DOCKER-SETUP.md

Production Readiness / Operations

For backup/restore, rollback, and operational procedures, see guides/OPERATIONS.md. For release go/no-go checks, see guides/PRODUCTION-READY-CHECKLIST.md.

Step 1: Set Up the Python Backend

The Desktop UI runs Python scripts behind the scenes. Set up the Python environment:

cd auto-codex

# Using uv (recommended)
uv venv && uv pip install -r requirements.txt

# Or using standard Python
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Production (deterministic installs): use the lock file that matches your Python version.

# Example for Python 3.12/3.13
PY_VER_NODOT=$(python3 -c 'import sys; print(f"{sys.version_info[0]}{sys.version_info[1]}")')
uv pip install -r requirements-py${PY_VER_NODOT}.lock

Step 2: Start the Memory Layer

The Auto-Codex Memory Layer provides cross-session context retention using a graph database:

# Pin image tags (required in production)
export FALKORDB_IMAGE_TAG=<version>
export GRAPHITI_MCP_IMAGE_TAG=<version>

# Make sure Docker Desktop is running, then:
docker-compose up -d falkordb

Step 3: Install and Launch the Desktop UI

cd auto-codex-ui

# Install dependencies (pnpm recommended, npm works too)
pnpm install
# or: npm install

# Dev mode (hot reload)
pnpm run dev
# or: npm run dev

# Production build + start
pnpm run build && pnpm run start
# or: npm run build && npm run start
Windows users: If installation fails with node-gyp errors, click here

Auto-Codex automatically downloads prebuilt binaries for Windows. If prebuilts aren't available for your Electron version yet, you'll need Visual Studio Build Tools:

  1. Download Visual Studio Build Tools 2022
  2. Select "Desktop development with C++" workload
  3. In "Individual Components", add "MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs"
  4. Restart terminal and run npm install again

Step 4: Start Building

  1. Add your project in the UI
  2. Create a new task describing what you want to build
  3. Watch as Auto-Codex creates a spec, plans, and implements your feature
  4. Review changes and merge when satisfied

Legacy Notes

  • .kiro/ (including .kiro/specs) is deprecated legacy tooling and is intentionally removed/ignored. Use .auto-codex/ for specs and task data.

🎯 Features

Kanban Board

Plan tasks and let AI handle the planning, coding, and validation — all in a visual interface. Track progress from "Planning" to "Done" while agents work autonomously.

Agent Terminals

Spawn up to 12 AI-powered terminals for hands-on coding. Inject task context with a click, reference files from your project, and work rapidly across multiple sessions.

Power users: Connect multiple OpenAI accounts to run even more agents in parallel — perfect for teams or heavy workloads.

Auto-Codex Agent Terminals

Insights

Have a conversation about your project in a ChatGPT-style interface. Ask questions, get explanations, and explore your codebase through natural dialogue.

Roadmap

Based on your target audience, AI anticipates and plans the most impactful features you should focus on. Prioritize what matters most to your users.

Auto-Codex Roadmap

Ideation

Let AI help you create a project that shines. Rapidly understand your codebase and discover:

  • Code improvements and refactoring opportunities
  • Performance bottlenecks
  • Security vulnerabilities
  • Documentation gaps
  • UI/UX enhancements
  • Overall code quality issues

Changelog

Write professional changelogs effortlessly. Generate release notes from completed Auto-Codex tasks or integrate with GitHub to create masterclass changelogs automatically.

Context

See exactly what Auto-Codex understands about your project — the tech stack, file structure, patterns, and insights it uses to write better code.

AI Merge Resolution

When your main branch evolves while a build is in progress, Auto-Codex automatically resolves merge conflicts using AI — no manual <<<<<<< HEAD fixing required.

How it works:

  1. Git Auto-Merge First — Simple non-conflicting changes merge instantly without AI
  2. Conflict-Only AI — For actual conflicts, AI receives only the specific conflict regions (not entire files), achieving ~98% prompt reduction
  3. Parallel Processing — Multiple conflicting files resolve simultaneously for faster merges
  4. Syntax Validation — Every merge is validated before being applied

The result: A build that was 50+ commits behind main merges in seconds instead of requiring manual conflict resolution.

CLI Usage (Terminal-Only)

For terminal-based workflows, headless servers, or CI/CD integration, see guides/CLI-USAGE.md.

Import Validation

Run a quick Python import validation across the repo:

./scripts/validate-imports.sh

How It Works

Auto-Codex focuses on three core principles: context engineering (understanding your codebase before writing code), good coding standards (following best practices and patterns), and validation logic (ensuring code works before you see it).

The Agent Pipeline

Phase 1: Spec Creation (3-8 phases based on complexity)

Before any code is written, agents gather context and create a detailed specification:

  1. Discovery — Analyzes your project structure and tech stack
  2. Requirements — Gathers what you want to build through interactive conversation
  3. Research — Validates external integrations against real documentation
  4. Context Discovery — Finds relevant files in your codebase
  5. Spec Writer — Creates a comprehensive specification document
  6. Spec Critic — Self-critiques using extended thinking to find issues early
  7. Planner — Breaks work into subtasks with dependencies
  8. Validation — Ensures all outputs are valid before proceeding

Phase 2: Implementation

With a validated spec, coding agents execute the plan:

  1. Planner Agent — Creates subtask-based implementation plan
  2. Coder Agent — Implements subtasks one-by-one with verification
  3. QA Reviewer — Validates all acceptance criteria
  4. QA Fixer — Fixes issues in a self-healing loop (up to 50 iterations)

Each session runs with a fresh context window. Progress is tracked via implementation_plan.json and Git commits.

Phase 3: Merge

When you're ready to merge, AI handles any conflicts that arose while you were working:

  1. Conflict Detection — Identifies files modified in both main and the build
  2. 3-Tier Resolution — Git auto-merge → Conflict-only AI → Full-file AI (fallback)
  3. Parallel Merge — Multiple files resolve simultaneously
  4. Staged for Review — Changes are staged but not committed, so you can review before finalizing

🔒 Security Model

Three-layer defense keeps your code safe:

  • OS Sandbox — Bash commands run in isolation
  • Filesystem Restrictions — Operations limited to project directory
  • Command Allowlist — Only approved commands based on your project's stack

🧠 Memory Layer

The Memory Layer is a hybrid RAG system combining graph nodes with semantic search to deliver the best possible context during AI coding. Agents remember insights from previous sessions, discovered codebase patterns persist and are reusable, and historical context helps agents make smarter decisions.

Architecture:

  • Backend: FalkorDB (graph database) via Docker
  • Library: Graphiti for knowledge graph operations
  • Providers: OpenAI, Anthropic, Azure OpenAI, Google AI, or Ollama (local/offline)
Setup LLM Embeddings Notes
OpenAI OpenAI OpenAI Simplest - single API key
Anthropic + Voyage Anthropic Voyage AI High quality
Google AI Gemini Google Single API key, fast inference
Ollama Ollama Ollama Fully offline
Azure Azure OpenAI Azure OpenAI Enterprise

FAQ

Q: How is Auto-Codex different from Cursor, Aider, Cline, or Claude Code? Auto-Codex is a desktop app + framework that orchestrates the OpenAI Codex CLI through a multi-agent pipeline (spec → plan → code → QA → merge) inside isolated git worktrees. Cursor is an IDE replacement; Aider is a single-agent REPL; Cline is a VS Code extension that drives one agent. Claude Code is Anthropic's terminal agent. Auto-Codex is the only one of these focused on running many long autonomous builds in parallel with a Kanban board, self-validating QA, and AI-driven merge-conflict resolution.

Q: Do I need an OpenAI API key, or does my Codex CLI subscription work? Either works. If you've already run codex login, Auto-Codex reads the token from ~/.codex/auth.json. For headless / CI use, set OPENAI_API_KEY, CODEX_CODE_OAUTH_TOKEN, or point CODEX_CONFIG_DIR at an existing Codex CLI config.

Q: Is my code sent to OpenAI / anywhere else? Only what Codex CLI itself sends — the same prompts and file contents a normal codex invocation would send. Auto-Codex adds no telemetry. The optional Memory Layer (FalkorDB) runs locally in Docker. Embeddings can be local (Ollama) for fully-offline memory.

Q: Will it ever break my main branch? No. Every build runs in an isolated git worktree under .worktrees/<spec-name>/ on a branch named auto-codex/<spec-name>. Nothing is pushed to your remote until you explicitly run --merge (or accept the merge in the UI) and then git push.

Q: What if a build runs forever or gets stuck? The QA loop has a max iteration count (50 by default), spec phases time out, and you can hit Stop in the UI. Worktrees can be discarded with python3 auto-codex/run.py --spec NNN --discard (CLI) or one-click in the UI.

Q: Does it work on Apple Silicon? Intel Macs? Windows? Linux? Yes to all four. Electron builds ship native binaries; Codex CLI itself is cross-platform. Windows users who hit node-gyp errors need Visual Studio Build Tools (see the collapsible note in Quick Start).

Q: Can I run it fully offline? The Memory Layer can (Ollama for both LLM and embeddings). The coding agents themselves require an OpenAI-compatible endpoint, so a local LLM via Codex CLI + Ollama proxy would work but is not officially supported.

Q: AGPL-3.0 — can I use this in my closed-source company project? You can use Auto-Codex to build your closed-source project (the code Auto-Codex generates for you belongs to you). You cannot embed Auto-Codex itself in a closed-source product or run it as a SaaS without open-sourcing under AGPL-3.0. Contact the maintainers for a commercial license.

Q: How do I migrate from Auto-Claude (the Anthropic-SDK fork)? See MIGRATION.md. TL;DR: the spec/plan/QA architecture is identical; only the agent backend changes from Claude SDK to Codex CLI.

Project Structure

your-project/
├── .worktrees/               # Created during build (git-ignored)
│   └── <spec-name>/          # Isolated workspace per spec (git worktree)
├── .auto-codex/              # Per-project data (specs, plans, QA reports)
│   ├── specs/                # Task specifications
│   ├── roadmap/              # Project roadmap
│   └── ideation/             # Ideas and planning
├── auto-codex/              # Python backend (framework code)
│   ├── run.py                # Build entry point
│   ├── runners/spec_runner.py # Spec creation orchestrator
│   ├── prompts/              # Agent prompt templates
│   └── ...
├── auto-codex-ui/           # Electron desktop application
│   └── ...
└── docker-compose.yml        # FalkorDB for Memory Layer

Understanding the Folders

You don't create these folders manually - they serve different purposes:

  • auto-codex/ - The framework repository itself (clone this once from GitHub)
  • .auto-codex/ - Created automatically in YOUR project when you run Auto-Codex (stores specs, plans, QA reports)
  • .worktrees/ - Isolated workspaces created during builds (git-ignored; clean up via --discard / --cleanup-worktrees when you no longer need them)

When using Auto-Codex on your project:

cd your-project/              # Your own project directory
python3 /path/to/auto-codex/run.py --spec 001
# Auto-Codex creates .auto-codex/ automatically in your-project/

When developing Auto-Codex itself:

git clone https://github.com/tytsxai/Auto-Codex.git
cd auto-codex/               # You're working in the framework repo

The .auto-codex/ directory is gitignored and project-specific - you'll have one per project you use Auto-Codex on.

Environment Variables (CLI Only)

Desktop UI users: These are configured through the app settings — no manual setup needed.

Existing users migrating from Claude SDK should read MIGRATION.md.

Variable Required Description
OPENAI_API_KEY One of OpenAI API key for Codex CLI and OpenAI-backed memory providers
CODEX_CODE_OAUTH_TOKEN One of OAuth token from Codex CLI login (e.g. codex login --device-auth)
CODEX_CONFIG_DIR One of Path to Codex CLI config directory for profile-based auth
AUTO_CODEX_DISABLE_DEFAULT_CODEX_CONFIG_DIR No Set to 1 to ignore the default ~/.codex config directory
AUTO_CODEX_BYPASS_CODEX_SANDBOX No Set to 0 to keep Codex CLI sandboxing enabled
AUTO_CODEX_LEGACY_SECURITY No Set to true to disable security flag enforcement (backwards compat)
AUTO_BUILD_MODEL No Model override (default: gpt-5.2-codex). Note: reasoning is a runtime parameter; legacy suffix input like -xhigh is accepted but discouraged (it is not a real model ID).
AUTO_BUILD_REASONING_EFFORT No Reasoning effort override (low/medium/high/xhigh)
GRAPHITI_ENABLED Recommended Set to true to enable Memory Layer
GRAPHITI_LLM_PROVIDER For Memory LLM provider: openai, anthropic, azure_openai, ollama, google
GRAPHITI_EMBEDDER_PROVIDER For Memory Embedder: openai, voyage, azure_openai, ollama, google
ANTHROPIC_API_KEY For Anthropic Required for Anthropic LLM
VOYAGE_API_KEY For Voyage Required for Voyage embeddings
GOOGLE_API_KEY For Google Required for Google AI (Gemini) provider

See auto-codex/.env.example for complete configuration options.

Contributing

We welcome contributions! Whether it's bug fixes, new features, or documentation improvements.

See CONTRIBUTING.md for guidelines on how to get started.

Acknowledgments

This project is a fork of Auto-Claude, adapted to use OpenAI Codex CLI. The original framework was inspired by Anthropic's Autonomous Coding Agent.

License

AGPL-3.0 - GNU Affero General Public License v3.0

Official license text: LICENSE (mirror copy: agpl-3.0.txt).

This software is licensed under AGPL-3.0, which means:

  • Attribution Required: You must give appropriate credit, provide a link to the license, and indicate if changes were made. When using Auto-Codex, please credit the project.
  • Open Source Required: If you modify this software and distribute it or run it as a service, you must release your source code under AGPL-3.0.
  • Network Use (Copyleft): If you run this software as a network service (e.g., SaaS), users interacting with it over a network must be able to receive the source code.
  • No Closed-Source Usage: You cannot use this software in proprietary/closed-source projects without open-sourcing your entire project under AGPL-3.0.

In simple terms: You can use Auto-Codex freely, but if you build on it, your code must also be open source under AGPL-3.0 and attribute this project. Closed-source commercial use requires a separate license.

For commercial licensing inquiries (closed-source usage), please contact the maintainers.