CodeFRAME™

[!WARNING] Prerequisite: CodeFRAME requires an API key matching your LLM provider — by default an ANTHROPIC_API_KEY from console.anthropic.com, or OPENAI_API_KEY when using --llm-provider openai (local providers like Ollama need no key). Get your key before running any cf command.

---

The IDE of the future is not a better text editor with AI autocomplete. It is a project delivery system where writing code is a subprocess.

---

The Problem

Coding agents are getting remarkably good at writing code. But shipping software is not the same as writing code.

Before code gets written, someone has to figure out what to build, decompose it into tasks that an agent can execute, and resolve ambiguities. After code gets written, someone has to verify it actually works, catch regressions, and deploy with confidence. Today, that "someone" is still you.

CodeFRAME owns the edges of the pipeline -- everything that happens before and after the code gets written. The actual coding is delegated to frontier agents (Claude Code, Codex, OpenCode, Kilocode, or CodeFRAME's built-in ReAct agent) that are better at it than any custom agent could be.

Think. Build. Prove. Ship.

THINK    What are you building? How should it be broken down?
           cf prd generate         Socratic requirements gathering
           cf prd stress-test      Recursive decomposition, surface ambiguities
           cf tasks generate       Atomic tasks with dependency graphs

BUILD    Delegate to the best coding agent for the job
           cf work start <task> --engine  Claude Code, Codex, OpenCode, Kilocode, or built-in
           CodeFRAME owns: verification gates, self-correction, stall detection

PROVE    Is the output any good?
           cf proof run            9-gate evidence-based quality system
           cf proof capture        Glitch becomes a permanent requirement
           cf proof list           All active proof obligations
           cf proof status         Summary across all gates
           cf proof show <id>      Requirement detail and evidence
           cf proof waive <id>     Waive a requirement with justification

SHIP     Deploy with confidence
           cf pr create            PR with proof report attached
           cf pr merge <number>    Only merges if proof passes

THE CLOSED LOOP
  Glitch in production
    -> cf proof capture
    -> New requirement
    -> Enforced on every future build
    = Quality compounding interest

---

Why CodeFRAME

Nobody else does the full upstream pipeline. Most orchestrators assume issues and specs already exist. CodeFRAME generates them through AI-guided Socratic discovery and recursive decomposition.

Agent-agnostic execution. CodeFRAME does not compete with Claude Code or Codex. It orchestrates them. The built-in ReAct agent is a capable fallback, not the point.

Quality memory (PROOF9). Every failure becomes a permanent proof obligation across 9 verification gates. Not just test coverage -- evidence-based verification that compounds over time. The closed loop is what turns a project into a learning system.

Radical simplicity. Single CLI binary, SQLite, no daemons, no infrastructure. Install and start building in under a minute.

---

[!NOTE] CodeFRAME is in public beta (0.9.4). The vision and the Golden Path CLI (cf init/prd/tasks/work/proof/pr) and v2 API are stable enough to build on; the web UI and anything marked "in progress" in docs/PRODUCT_ROADMAP.md are still moving, and on-disk .codeframe/ formats may change between betas. Expect rough edges and tell us about them.

Quick Start

Step 1 — Install

uv tool install codeframe-ai     # installs the `cf` command globally
cf --help                        # smoke test — should print the command tree

No uv? pipx install codeframe-ai works too, or run without installing via uvx codeframe-ai --help. (The PyPI package is codeframe-ai; the command is cf.)

<details> <summary>Install from source (for contributors)</summary>

git clone https://github.com/frankbria/codeframe.git && cd codeframe
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv && source .venv/bin/activate && uv sync
uv run cf --help

When working from source, prefix the commands below with uv run.

</details>

Step 2 — Set your API key

export ANTHROPIC_API_KEY="sk-ant-..."   # get yours at https://console.anthropic.com/
# or store it once instead: cf auth setup --provider anthropic

Step 3 — Initialize your project

cf init /path/to/your/project --detect

Step 4 — Think: generate a PRD and tasks

cf prd generate          # AI-guided Socratic requirements discovery
cf tasks generate        # Decompose PRD into atomic tasks with dependencies
cf tasks list            # Review what was generated

Step 5 — Promote one task

cf tasks generate creates tasks in BACKLOG so you can review them before an agent touches your code. Pick one and move it to READY — cf tasks list prints an 8-character ID for each task, and that prefix is all you need:

cf tasks list                            # copy the ID of the task you want
cf tasks set status <task-id> READY      # note: id before status

Start with one. A generated backlog is typically 20+ tasks, and your first run should show you the loop, not build the whole project in one sitting.

Step 6 — Build: hand the task to an agent

cf work start <task-id> --execute

Step 7 — Prove: capture a requirement, then verify it

PROOF9 verifies obligations, and a new workspace has none — so verifying it first would report that nothing was checked and exit 2. That is deliberate: a run that checked nothing is not a pass. Give it something to check.

cf proof capture \
  --title "add() returns the wrong sum for negative numbers" \
  --description "Calculation is wrong: add(-1, -1) returned 0 instead of -2" \
  --where src/calc.py --severity high --source qa

That creates a requirement, picks the gates that would have caught it, and writes a draft test stub per gate under tests/proof/<REQ-ID>/. The stubs are named draft_*.py so pytest does not collect them yet, and each one is a placeholder assert False. Turn them into real tests — drop the draft_ prefix from each filename, and replace the placeholder with an assertion that actually proves the bug is fixed:

ls tests/proof/REQ-0001/          # draft_test_..._unit.py, draft_test_..._contract.py
# rename each to test_*.py and write the real assertion

Now the gates have evidence to collect:

cf proof run --full               # -> All obligations satisfied. (exit 0)

--full checks every open requirement; plain cf proof run checks only the ones your current diff touches. The unit and contract gates run your project's pytest, so the project needs pytest available (uv add --dev pytest) — a gate with no way to run is reported as unverified, never as a pass.

This is the loop that compounds: every glitch you capture stays a permanent check, and cf pr merge refuses to merge while any of them is open.

Step 8 — Ship

cf pr talks to GitHub, so it needs a token and the repository: connect them in the web UI (Settings → Integrations), or export GITHUB_TOKEN (a PAT with repo scope) and GITHUB_REPO=owner/repo.

cf pr create                        # Open a PR with proof report attached

The title defaults to the branch's newest commit (--title overrides it), and the body ends with the workspace's PROOF9 status: requirement counts, the open ones by name, and the latest cf proof run verdict.

That is the entire workflow. An empty directory through a green cf proof run is 5m59s of wall clock on a clean machine — measured, not estimated, in this walkthrough — most of it in cf prd generate and the agent run; Step 7 costs 7 seconds of it. cf pr create needs a GitHub remote, so it is outside that measurement.

If the agent needs a decision it cannot make, it stops and files a blocker rather than guessing — cf blocker list shows it and cf blocker answer <id> "..." unblocks the task.

<details> <summary>Running the whole backlog</summary>

Once you trust the loop, promote everything and let it run:

cf tasks set status READY --all --from BACKLOG   # every BACKLOG task
cf work batch run --all-ready                    # execute them

This is long-running — each task is a full agent run, and serial is the default strategy — so start it and watch it from another terminal rather than waiting on the prompt:

cf work batch status              # lists recent batches and their IDs
cf work batch follow <batch-id>   # live progress for one of them

--strategy parallel --max-parallel 4 and --retry 2 are worth knowing about before you kick off a large batch; see docs/QUICKSTART.md.

</details>

See it run from scratch. Cold start on a clean machine is a narrated walkthrough of exactly these steps in a throwaway container — real transcripts, per-step timings, and the rough edges left in. Reproduce it with scripts/quickstart-cleanroom/run.sh.

---

Architecture

    YOU
     |
     v
  +-THINK---------------------------------------------+
  |  cf prd generate    Socratic requirements          |
  |  cf tasks generate  Atomic decomposition           |
  +----------------------------+-----------------------+
                               |
                               v
  +-BUILD---------------------------------------------+
  |  cf work start <task> --engine <agent>             |
  |                                                    |
  |  +-- Claude Code / Codex / OpenCode / Kilocode / ReAct        |
  |  |                                                 |
  |  +-- Verification gates (ruff, pytest, BUILD)      |
  |  +-- Self-correction loop (up to 5 retries)        |
  |  +-- Stall detection -> retry / blocker / fail       |
  +----------------------------+-----------------------+
                               |
                               v
  +-PROVE---------------------------------------------+
  |  cf proof run       9-gate quality system          |
  |  cf review          Verification gates             |
  +----------------------------+-----------------------+
                               |
                               v
  +-SHIP----------------------------------------------+
  |  cf pr create       PR with proof report           |
  |  cf pr merge <n>    Merge if proof passes          |
  +---------------------------------------------------+
                               |
            Glitch in production?
                               |
                               v
            cf proof capture -> new requirement
            -> enforced forever (closed loop)

The core domain is headless and runs entirely from the CLI. The FastAPI server and web UI are optional adapters for teams that want a dashboard.