CodeFRAME™

A project delivery system for AI-written software.
CodeFRAME owns everything before and after the code: requirements, task planning, verification and release.
The coding itself goes to the agent of your choice.

Quick start · Demos · CLI guide · proof9 plugin · Docs · Changelog

---

Overview

Coding agents have become very good at writing code, but writing code is not the same as shipping software. Before the code, someone decides what to build, breaks it into tasks an agent can finish, and resolves the ambiguities. After it, someone checks that it works, makes sure old bugs stay fixed, and merges with confidence. Today that someone is still you.

CodeFRAME automates those two edges. It turns an idea into a PRD and a dependency-ordered task graph, delegates each task to Claude Code, Codex, OpenCode, Kilocode or its built-in ReAct agent, verifies the result against an evidence-based quality ledger, and refuses to merge while a known problem is still open.

Stage	What CodeFRAME does	Commands
Think	Socratic requirements discovery, ambiguity stress-testing, task decomposition with dependencies	cf prd generate · cf prd stress-test · cf tasks generate
Build	Runs each task on the engine you choose, with verification gates, self-correction, stall detection and human-in-the-loop blockers	cf work start --engine … · cf work batch run
Prove	PROOF9: every glitch becomes a permanent requirement, verified across nine gates with checksummed evidence	cf proof capture · cf proof run
Ship	Pull requests carry the proof report; merge is blocked while an in-scope requirement is open	cf pr create · cf pr merge

The result is a closed loop: a bug found in production becomes a requirement, and that requirement is checked on every build that follows.

Other tools remember what your reviewers prefer. CodeFRAME remembers what actually broke, and proves it stays fixed: evidence is checksummed and bound to the run and gate that produced it, a run that verified nothing is reported as vacuous rather than green, and every waiver records who approved it, why, and (when set) when it expires. Where each of those lives in the code is listed in VISION.md.

Note

CodeFRAME is in public beta (0.9.7). The Golden Path CLI (cf init/prd/tasks/work/proof/pr) is stable enough to build on. Anything marked in progress in the roadmap is still moving, and on-disk .codeframe/ formats may change between betas. Report rough edges.

---

See it in action

Command line

The CLI is the primary interface and needs no server. Below, a real session initializes a workspace, imports a PRD, generates 18 dependency-ordered tasks with one LLM call, and captures a bug as a PROOF9 requirement.

_{Sped up; the LLM wait is trimmed. Full walkthrough and command reference: CLI guide.}

In Claude Code

The proof9 plugin brings the proof ledger into a Claude Code session: /proof captures a bug or locks in passing tests, every commit Claude makes is checked against the ledger first, and a failing requirement shows above the prompt. A ledger pane beside the transcript lists every requirement with its evidence and run history.

A real session on codeframe 0.9.7 (cast: docs/images/proof9-loop.cast). Asked for a change that would undo a past decision, Claude finds the locked requirement, keeps it, and says what it would take to change it on purpose.

---

Quick Start

Prerequisites: Python 3.11+, git, and an API key for your LLM provider. By default that is ANTHROPIC_API_KEY from console.anthropic.com. OPENAI_API_KEY works with --llm-provider openai, and local providers such as Ollama need no key.

1. Install

uv tool install codeframe-ai     # installs the `cf` command
cf --help

pipx install codeframe-ai works too, or run it without installing via uvx --from codeframe-ai cf --help. The package is codeframe-ai; the command is cf.

2. Set your API key

export ANTHROPIC_API_KEY="sk-ant-..."
# or store it once: cf auth setup --provider anthropic

3. Think: requirements and tasks

cd /path/to/your/project
cf init . --detect       # create the workspace, detect the tech stack
cf prd generate          # Socratic discovery (or: cf prd add PRD.md)
cf tasks generate        # dependency-ordered tasks, created in BACKLOG
cf tasks list

4. Build: run one task

cf tasks set status <task-id> READY
cf work start <task-id> --execute                       # built-in agent
cf work start <task-id> --execute --engine claude-code  # or codex, opencode, kilocode

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

5. Prove: capture a requirement, then verify it

cf proof capture --title "add() is wrong for negatives" \
  --description "add(-1, -1) returned 0" --where src/calc.py --severity high --source qa
# turn the generated tests/proof/REQ-0001/draft_*.py stubs into real tests, then:
cf proof run --full

cf proof capture also works on its own in any git repository. It creates .codeframe/ on first use, so you can start recording defects without cf init. To start from the tests you already have, cf proof ratchet locks every currently-passing test in as a requirement, so it cannot silently stop passing.

In Claude Code: the proof9 plugin. At the prompt of a Claude Code session:

/plugin install proof9 --marketplace frankbria/codeframe

(From a shell: claude plugin install proof9 --marketplace frankbria/codeframe.) It adds /proof to capture a bug or lock in passing tests, checks the ledger before every commit Claude makes (warning by default), and shows a failing requirement above the prompt. It needs codeframe-ai 0.9.7 or later on your PATH. See proof9/README.md.

6. Ship

export GITHUB_TOKEN=... GITHUB_REPO=owner/repo
cf pr create
cf pr merge <number>     # refused while an in-scope requirement is open

An empty directory through a green cf proof run takes about 6 minutes on a clean machine: measured, step by step. The CLI guide explains each step in depth, including batch runs over a whole backlog.

Install from source (contributors)

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

---

Features

Think

• Socratic PRD discovery that stops on its own: at most 10 questions by default, an early stop once coverage plateaus, a duplicate-question guard, and /done to finish on demand. Uncovered areas become open questions in the PRD.
• Stress testing extracts every goal, analyzes it, and returns severity-tagged ambiguities that you answer to refine the PRD.
• Task decomposition into atomic tasks with a dependency graph, 5 PRD templates, 7 task templates, and CPM-based schedule prediction.
• GitHub Issues import: turn a repository's open issues into tasks that link back and close the issue when done.

Build

• Agent-agnostic execution: Claude Code, Codex, OpenCode, Kilocode, or the built-in ReAct agent, selected per run with --engine.
• Verification gates (ruff, pytest, build) with a self-correction loop and loop prevention.
• Stall detection with configurable recovery: retry, raise a blocker, or fail.
• Batch execution: serial, parallel, or auto (LLM-inferred dependencies), with retries and git worktree isolation for parallel agents.
• Human-in-the-loop blockers, checkpoints, replay of past runs, and a TUI dashboard.
• Multi-provider LLM: Anthropic by default, or any OpenAI-compatible endpoint (OpenAI, Ollama, vLLM, LM Studio).

Prove

• PROOF9 quality memory: nine gates (unit, contract, e2e, visual, a11y, perf, sec, demo, manual). A captured glitch gets its obligations and draft test stubs generated automatically.
• Evidence you can trust: artifacts are checksummed and bound to the run and gate that produced them. A run that verified nothing is reported as vacuous, never as a pass.
• Every gate has a real check: UNIT and CONTRACT run pytest and SEC runs bandit. E2E, VISUAL, A11Y, PERF and DEMO are enforced through their evidence rules: each obligation gets a test_a11y_* / test_perf_* / … test that runs by name, and a missing test is a failure. MANUAL is resolved only by a justified waiver.
• Scoped runs: cf proof run checks the requirements your uncommitted changes touch, satisfied ones included, and --full checks every requirement except waived ones.
• Waivers require a reason, record who approved them, can expire, and stay in the audit trail.

Ship

• Pull requests with a proof report attached to the body.
• Merge gate enforced in cf pr merge, scoped to the PR's changed files (renames included). An override requires a reason and is recorded in an audit ledger.
• Cost tracking per task, per agent and per day (cf stats).

Platform

• CLI-first: the whole pipeline runs from the terminal with no server. SQLite storage, no daemons.
• proof9 Claude Code plugin: the proof ledger inside a Claude Code session, with a pre-commit check on every commit Claude makes.
• TUI dashboard (cf dashboard) for watching a workspace from the terminal.

---

Architecture

     ┌──────────── cf CLI · cf dashboard (TUI) ────────────┐   ┌── proof9 plugin (Claude Code) ──┐
     │  direct calls, no server required                   │   │  runs cf proof … --json         │
     └──────────────────────────┬──────────────────────────┘   └────────────────┬────────────────┘
                                ▼                                               ▼
     ┌────────────────────────────────────────────────────────────────────────────────────────┐
     │  codeframe/core: headless domain and orchestration                                     │
     │  THINK  prd · discovery · stress test · tasks · dependency graph                       │
     │  BUILD  runtime · conductor · gates · self-correction · stall detection                │
     │  PROVE  PROOF9 ledger · scope · evidence                                               │
     │  SHIP   GitHub PRs · merge gate                                                        │
     └───────────┬──────────────────────────────┬─────────────────────────────────────────────┘
                 ▼                              ▼
  Coding engines                       LLM providers                 Storage
  Claude Code · Codex · OpenCode       Anthropic · OpenAI ·          .codeframe/state.db
  Kilocode · built-in ReAct            any OpenAI-compatible         (per workspace)

The core is headless and runs entirely from the CLI; the proof9 plugin drives it through cf proof. See Agent System Reference for the execution flows.

---

Configuration

# Required for the default provider
export ANTHROPIC_API_KEY=sk-ant-...

# Another provider (optional)
export CODEFRAME_LLM_PROVIDER=openai             # anthropic | openai | ollama | vllm | compatible
export CODEFRAME_LLM_MODEL=gpt-4o
export OPENAI_API_KEY=sk-...                     # not needed for local providers
export OPENAI_BASE_URL=http://localhost:11434/v1 # Ollama, vLLM, LM Studio, ...

Per-workspace settings live in .codeframe/config.yaml (an llm: block, and discovery_max_questions). For the LLM provider and model, precedence is CLI flag, then environment, then workspace config, then default.

Privacy and telemetry

Telemetry is opt-in and off by default. When enabled it sends the command name, duration, exit code, version and OS, never code, prompts, arguments or file paths. Control it with cf config telemetry on|off|status, CODEFRAME_TELEMETRY=on|off, or DO_NOT_TRACK=1. See PRIVACY.md.

---

Documentation

Guide	What's in it
CLI guide	Walkthrough plus the complete command reference
proof9 plugin	The proof ledger inside Claude Code
Quickstart	Install, keys, first run
Cold start on a clean machine	A measured, narrated run of the Golden Path
Golden Path	The CLI-first workflow contract
Product roadmap	Phase plan and feature status
Vision	The Think → Build → Prove → Ship thesis
Agent system reference	Agent components, model selection, execution flows
ReAct agent architecture	Tools, editor, token management

---

Roadmap

Think, Build, Prove and Ship all work end to end from the CLI. The web UI and server were removed in #1477; the CLI and the proof9 plugin are the product. The product roadmap is the authority on phase status.

Next up

• Post-merge glitch capture loop
• Engine performance tracking and automatic routing
• Specification-level dependency analysis

Shipped

Think

• cf prd stress-test: recursive decomposition that surfaces ambiguities before execution
• Multi-round PRD refinement with domain-specific probes

Build

• Agent adapter architecture: delegate to Claude Code, Codex, OpenCode, Kilocode
• Worktree isolation for parallel agent execution
• Reconciliation layer for multi-agent output
• Replay/debug mode (cf work replay, built-in ReAct engine)
• TUI dashboard (cf dashboard)
• Dynamic config reload during batch execution
• Multi-provider LLM: Anthropic, OpenAI, or any OpenAI-compatible endpoint

Prove

• PROOF9: 9-gate evidence-based quality system
• cf proof capture: the glitch-to-requirement closed loop
• cf proof ratchet: lock in every currently-passing test
• proof9 Claude Code plugin: /proof, pre-commit ledger check, ledger pane

Ship

• Merge gating on PROOF9 pass in cf pr merge, scoped to the PR's files, with an audited override (actor + reason)

---

Contributing

uv sync --extra dev && pre-commit install
uv run pytest tests/ --ignore=tests/e2e -m "not lifecycle"   # the CI gate
uv run ruff check .

The suite has 5,000+ tests, and contributions need 80% test coverage, the floor CI enforces. Code standards are ruff, type hints and tests with every change. During the beta, feature ideas go to Discussions → Ideas before code. See CONTRIBUTING.md for what is stable and how to propose changes.

---

Security, licensing and support

• Security: report vulnerabilities privately through GitHub private vulnerability reporting or security@codeframe.sh, never in a public issue. See SECURITY.md.
• Licensing: CodeFRAME is Apache-2.0. LICENSING.md explains what that allows and the few things it asks of you. A hosted offering and commercial support are planned: licensing@codeframe.sh.
• Trademark: the CodeFRAME name and logo are trademarks and are not covered by the code license. See TRADEMARKS.md before using the name for a fork or product.
• Design partners: we are recruiting 5–10 teams for the beta cohort. See DESIGN_PARTNERS.md, then email hello@codeframe.sh or reply to the pinned Discussion.
• Help: Q&A for questions, Ideas for feature requests, and issues for confirmed bugs.

---

License

Apache-2.0: free to use, modify and distribute, including in commercial and closed-source products. Keep the license and NOTICE file with any copy you distribute, and mark the files you change. See LICENSING.md for a plain-language explanation.

The CodeFRAME™ name and logo are trademarks of Noatak Enterprises, LLC, dba Bria Strategy Group, and are not licensed under Apache-2.0. See TRADEMARKS.md.

---

Built by Frank Bria
Issues · Discussions · Documentation

_{CodeFRAME™ is a trademark of Noatak Enterprises, LLC, dba Bria Strategy Group. All rights reserved.}