CodeFRAME

At a Claude Code prompt:

/plugin install proof9 --marketplace frankbria/codeframe

The plugin needs the cf CLI on your PATH: uv tool install codeframe-ai.

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.

TDD protects your code. This protects your tests. Your agent can edit a test as easily as it can edit the code, and when a test is inconvenient that is often what it edits. A requirement is a test it cannot quietly drop: releasing one takes a waiver with a name, a reason and an expiry date.

---

Overview

Coding agents have become very good at writing code. What they have no memory of is what already went wrong. A bug you found, fixed and moved on from is, to the agent, just more code it is free to change next week.

CodeFRAME gives it that memory. A defect is recorded as a requirement, scoped to the code it affects, with a named test that proves it stays fixed. Every later change to that code is checked against it — before the commit in a Claude Code session, and again before the merge. Nothing is dropped silently: a requirement is released only by a recorded waiver.

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.

The same CLI also covers the work before the code — requirements discovery, task decomposition, and delegating each task to Claude Code, Codex, OpenCode, Kilocode or its built-in agent. See Features.

Proof of substance. 6,000+ automated tests passing in CI, an 80% test coverage floor CI enforces, and a sample evidence report showing what a run actually produces.

[!NOTE] CodeFRAME is in public beta (0.9.8). 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

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.

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.

---

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.

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

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

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 regression 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 is enforced; you write the tests for five of them. UNIT and CONTRACT run pytest and SEC runs bandit with no work from you. E2E, VISUAL, A11Y, PERF and DEMO generate a named stub per obligation — test_a11y_*, test_perf_* and so on — which you implement; the gate then runs it by name, and a missing test is a failure, never a pass. MANUAL is never machine-verified and 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.

---

What we don't do yet

Published deliberately. Extended rather than quietly shortened.

• CodeFRAME does not judge whether a test is meaningful. A test that runs and passes passes here too, including an over-mocked or tautological one. What it does is source the requirement from a real captured defect, so the test has an actual failing input to satisfy.
• You write the tests for five of the nine gates. UNIT, CONTRACT and SEC run on their own. E2E, VISUAL, A11Y, PERF and DEMO generate named stubs you implement. MANUAL is never machine-verified.
• The pre-commit check warns by default. Refusing a commit is opt-in (/config, mode: block). In block mode it fails closed: if the check cannot run, the commit is denied rather than waved through.
• The loop is not automatic. Post-merge glitch capture is not built. A person runs cf proof capture.
• There is no hosted offering and no published commercial license. Both are planned.
• Not enterprise-ready. SQLite only, no SSO, no RBAC, no multi-tenancy.
• No named design partners yet. The cohort is being recruited.

---

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

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 6,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 [email protected], 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: [email protected].
• 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 [email protected] 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.

CodeFRAME® is a registered trademark, and the CodeFRAME logo and PROOF9™ are trademarks, of Noatak Enterprises, LLC, dba Bria Strategy Group. None of them are licensed under Apache-2.0. See TRADEMARKS.md.

---