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 · Web UI guide · 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.

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

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

Web UI

The optional web UI puts the same workspace in the browser. The tour covers the overview, the PRD, the task board, PROOF9 requirements and their evidence, the review diff, and costs.

Task board: Kanban, dependencies, batch runs, per-task cost	PROOF9: requirements, gate runs, waivers with audit trail
Review: diff, gates, commit and pull request	Costs: spend by day, task and agent

_{Every page, explained: Web UI 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 codeframe-ai --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.

6. Ship

export GITHUB_TOKEN=... GITHUB_REPO=owner/repo   # or connect in Settings → Integrations
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 only the requirements your diff touches, 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 server-side and 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, plus an optional per-user daily spend limit on the server.

Platform

• CLI-first: the whole pipeline runs from the terminal with no server. SQLite storage, no daemons.
• Optional server and web UI: FastAPI v2 API (OpenAPI docs, API keys, scoped JWT auth, rate limiting, SSE and WebSocket streams) and a Next.js dashboard with interactive agent sessions and an in-browser terminal.
• Notifications: in-app and browser notifications, plus an outbound webhook for batch completions, blockers and merges.

Architecture

            ┌──────────────── cf CLI ────────────────┐     ┌──── Web UI (Next.js) ────┐
            │  direct calls, no server required      │     │  REST · SSE · WebSocket  │
            └───────────────────┬────────────────────┘     └────────────┬─────────────┘
                                │                                       │
                                │                      ┌────────────────▼─────────────┐
                                │                      │  FastAPI server (optional)   │
                                │                      │  thin adapter, auth, limits  │
                                ▼                      └────────────────┬─────────────┘
            ┌───────────────────────────────────────────────────────────▼─────────────┐
            │  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 server and web UI are optional adapters over it. 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.

Running the server needs AUTH_SECRET and WORKSPACE_ROOT; see the Quickstart and the deployment guide for every server, auth and rate-limit option.

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 and the browser. 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 .
cd web-ui && npm ci && npm test && npm run build              # web UI

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