CodeFRAME®

Your coding agent can’t quietly undo what you already decided.
Every bug you fix once, fixed forever: recorded as a requirement, locked to the code it affects,
and checked before every commit. Regression memory for coding agents.

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

/plugin install proof9 --marketplace frankbria/codeframe
_{At a Claude Code prompt. Needs the cf CLI: uv tool install codeframe-ai.}

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.

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

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.

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.

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.

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.}

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

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

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

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.

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.

Built by Frank Bria
Issues · Discussions · Documentation

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