llms.txt

# 自主编码代理 / autonomous-coding (Codex CLI fork)

> Local fork of Anthropic's `autonomous-coding` quickstart, switched to **Codex CLI as the agent backend** (with the Claude path retained). Drives a two-agent loop — an **init agent** that converts `prompts/app_spec.txt` into a `feature_list.json`, then a **coding agent** that implements features one at a time and marks each test green. Adds a stagnation-detection + repair-agent fallback, auto-resume from saved progress, multi-credential resolution, and a Bash command allowlist.

This repository is a **derivative work** of Anthropic's quickstart; if you want the original Claude-SDK-based implementation, link is in the README. The reason this fork exists: Codex CLI users want the same autonomous-build loop pattern without bringing in the Anthropic SDK.

## Key docs

- [README.md](README.md): Quick start, two skill commands (`/create-spec`, `/autonomous`), prerequisites.
- [.claude/CLAUDE.md](.claude/CLAUDE.md): Skill descriptions + architecture overview + workflow + credential resolution + known limits.
- [prompts/app_spec.txt](prompts/app_spec.txt): The spec file the init agent reads.
- Upstream: https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding

## What this does

- **Two-agent loop**:
  1. Init agent reads `prompts/app_spec.txt`, generates `feature_list.json` (the build plan)
  2. Coding agent implements features one at a time, marks tests green
- **Auto-stagnation handling**: 5 rounds of zero progress → switch to repair mode for 2 rounds; if still stuck, stop cleanly
- **Init-self-heal**: if the first init pass doesn't produce a valid feature list, retry up to 2 times
- **Resume safety**: progress lives in `feature_list.json`; interrupt and re-run anytime, picks up where it stopped
- **Backend choice**: Codex CLI default, Claude SDK still selectable via `client_factory.py`
- **Multi-credential resolution**: `OPENAI_API_KEY` env → `~/.codex/auth.json` → `~/.codex/config.toml` (third-party gateways like Yunyi)
- **Bash command allowlist** (`security.py`): blocks command substitution (`` `...` ``, `$(...)`, `<(...)`), restricts `rm` to safe relative paths
- **Test-count + webhook progress reporting** via `progress.py`

## What this does NOT do

- ❌ Build non-Node-Web apps — currently locked to Node.js / Web app generation
- ❌ Run with full sandbox/approvals enabled — Codex CLI is invoked with high-permission mode by default (read `.claude/CLAUDE.md` "Known limits")
- ❌ Replace the upstream Anthropic implementation — for the canonical version, use the upstream link
- ❌ Provide a hosted version — local-only, your machine's Codex CLI credentials
- ❌ Build mobile / desktop / native apps

## Common questions

- **Why a fork instead of using upstream?** Upstream uses the Anthropic SDK. This fork swaps in Codex CLI as the agent backend for users who prefer OpenAI's Codex pricing/UX.
- **Do I need both Codex CLI and Claude SDK?** No — pick one. The factory picks the active backend at startup.
- **First run takes 10–20 minutes?** Yes — generating the feature list and the initial test scaffolding is the slow phase. After that, each feature is incremental.
- **Where do builds land?** `generations/<project_name>/` under the repo. Use `/autonomous my_app` from Claude Code or `python3 autonomous_agent_demo.py --project-dir generations/my_app` directly.
- **Can I make the spec without Claude Code?** Yes — manually edit `prompts/app_spec.txt`. The `/create-spec` skill is just an interactive helper.

## Repository

- GitHub: https://github.com/tytsxai/autonomous-coding
- Upstream: https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding (Anthropic)
- License: see LICENSE (inherits upstream)
- Language: Python
- Author: tytsxai (fork) · Anthropic (upstream)

## Useful search phrases

- autonomous coding agent, autonomous web app builder, AI 自主编码代理, 自主构建 Web 应用 AI, Codex CLI autonomous coding fork, autonomous-coding quickstart Codex, Anthropic autonomous coding 中文版, two-agent coding loop, feature_list.json autonomous build, stagnation detection coding agent, Codex CLI 自主构建, AI auto-build Node.js app