codeframe-ai 0.9.0

A project delivery system that orchestrates frontier coding agents: Think, Build, Prove, Ship.

CodeFRAME

[!WARNING] Prerequisite: CodeFRAME requires an ANTHROPIC_API_KEY from console.anthropic.com. 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 --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             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.0). 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.)

Install from source (for 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

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

Step 2 — Set your API key

export ANTHROPIC_API_KEY="sk-ant-..."   # get yours at https://console.anthropic.com/

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 — Build, Prove, and Ship

cf work batch run --all-ready   # Execute all READY tasks (delegates to agent)
cf proof run                    # Run PROOF9 quality gates
cf pr create                    # Open a PR with proof report attached

That is the entire workflow. Everything else is optional.

---

Architecture

    YOU
     |
     v
  +-THINK---------------------------------------------+
  |  cf prd generate    Socratic requirements          |
  |  cf tasks generate  Atomic decomposition           |
  +----------------------------+-----------------------+
                               |
                               v
  +-BUILD---------------------------------------------+
  |  cf work start --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        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.

---

CLI Reference

All commands below assume the virtual environment is active (source .venv/bin/activate). If it is not active, prefix every cf command with uv run — e.g., uv run cf init ..

THINK -- Requirements and Planning

# Workspace
cf init <path>                        # Initialize workspace
cf init <path> --detect               # Auto-detect tech stack
cf status                             # Workspace status

# Requirements
cf prd generate                       # AI-guided Socratic PRD creation
cf prd generate --template lean       # Use a specific template
cf prd add <file.md>                  # Import existing PRD
cf prd show                           # Display current PRD

# Task decomposition
cf tasks generate                     # Generate tasks from PRD (LLM-powered)
cf tasks list                         # List all tasks
cf tasks list --status READY          # Filter by status
cf tasks show <id>                    # Task details with dependencies

# Scheduling
cf schedule show                      # Task schedule with dependencies
cf schedule predict                   # Completion date estimates
cf schedule bottlenecks               # Identify blocking tasks

# Migration / on-ramps
cf import ralph [path]                # Import a ralph-claude-code project
cf import ralph [path] --dry-run      # Preview mapping without changes
cf import ralph [path] -w <workspace> # Import into a specific workspace

BUILD -- Execution

# Single task
cf work start <id> --execute          # Execute with default engine (ReAct)
cf work start <id> --execute --engine plan   # Use legacy plan engine
cf work start <id> --execute --verbose       # Detailed progress output
cf work start <id> --execute --dry-run       # Preview without applying
cf work start <id> --execute --stall-timeout 120   # Custom stall timeout (seconds)
cf work start <id> --execute --stall-action retry  # Auto-retry on stall (blocker|retry|fail)
cf work start <id> --execute --llm-provider openai --llm-model gpt-4o  # Use OpenAI
cf work start <id> --execute --llm-provider openai --llm-model qwen2.5-coder:7b  # Use Ollama
cf work follow <id>                   # Stream live output
cf work stop <id>                     # Cancel a run
cf work resume <id>                   # Resume after answering blockers

# Batch execution
cf work batch run --all-ready                # All READY tasks
cf work batch run --strategy parallel        # Parallel execution
cf work batch run --strategy auto            # LLM-inferred dependencies
cf work batch run --retry 3                  # Auto-retry failures
cf work batch status [batch_id]              # Batch progress
cf work batch resume <batch_id>              # Re-run failed tasks

# Blockers (human-in-the-loop)
cf blocker list                       # Questions the agent needs answered
cf blocker show <id>                  # Blocker details
cf blocker answer <id> "answer"       # Unblock the agent

# Diagnostics
cf work diagnose <id>                 # AI-powered failure analysis
cf env check                          # Validate environment
cf env doctor                         # Comprehensive health check

PROVE -- Verification

# PROOF9 quality memory
cf proof run                          # Run all 9 proof gates
cf proof capture                      # Capture glitch as permanent requirement
cf proof list                         # List all proof requirements
cf proof status                       # Summary status across all gates
cf proof show <id>                    # Detail for a specific requirement
cf proof waive <id> --reason "..."    # Waive a requirement with justification

# Checkpoints and gates
cf review                             # Run verification gates
cf checkpoint create "milestone"      # Snapshot project state
cf checkpoint list                    # List checkpoints
cf checkpoint restore <id>            # Roll back to checkpoint

# Debugging
cf work replay <id>                   # Replay and debug a past execution
cf tui                                # Launch TUI dashboard

SHIP -- Delivery

cf pr create                          # Create PR from current branch
cf pr status                          # PR status and review state
cf pr checks                          # CI check results
cf pr merge                           # Merge approved PR
cf commit                             # Commit verified changes
cf patch export                       # Export changes as patch

---

What Works Today

CodeFRAME delivers the full Think-Build-Prove-Ship loop from the CLI and browser:

• THINK: Socratic PRD generation with recursive stress-testing, LLM-powered task decomposition with dependency graphs, 5 PRD templates, 7 task templates, CPM-based scheduling
• BUILD: ReAct agent with 7 tools, self-correction with loop prevention, verification gates (ruff/pytest/BUILD), stall detection with configurable recovery (retry/blocker/fail), batch execution (serial/parallel/auto), human-in-the-loop blockers, checkpointing, state persistence, replay/debug mode (cf work replay), dynamic config reload, TUI dashboard (cf tui)
• PROVE: PROOF9 quality memory system — 9-gate evidence-based verification (cf proof run/capture/list/status/show/waive), every glitch becomes a permanent proof obligation
• SHIP: GitHub PR workflow, environment validation, task self-diagnosis
• Engine adapters: Claude Code, Codex, OpenCode, Kilocode, and built-in ReAct — all via --engine flag
• Multi-provider LLM: Anthropic (default) or any OpenAI-compatible endpoint (OpenAI, Ollama, vLLM, LM Studio, Qwen, Deepseek) via --llm-provider / --llm-model or env vars
• Server layer (optional): FastAPI with 16+ v2 routers, API key auth, rate limiting, SSE streaming, WebSocket endpoints (agent chat, interactive terminal), OpenAPI docs
• Web UI: Workspace view, PRD discovery, Task board, Blocker resolution, Review/commit, PROOF9 requirements list + per-gate evidence display + run history panel + waiver audit trail, agent chat panel with streaming tool-call display, interactive terminal for session workspaces, Sessions list with active-session badge
• Test suite: 4200+ tests, 88% coverage

---

Roadmap

THINK (upstream pipeline)

• cf prd stress-test -- Recursive decomposition that surfaces ambiguities before execution
• Multi-round PRD refinement with domain-specific probes
• Specification-level dependency analysis

BUILD (agent adapters)

• Agent adapter architecture -- delegate to Claude Code, Codex, OpenCode, Kilocode via workspace hooks
• Worktree isolation for parallel agent execution
• Reconciliation layer for multi-agent output
• Replay/debug mode (cf work replay)
• TUI dashboard (cf tui)
• Dynamic config reload during batch execution
• Multi-provider LLM -- Anthropic, OpenAI, or any OpenAI-compatible endpoint
• Engine performance tracking and automatic routing

PROVE (quality memory)

• PROOF9 -- 9-gate evidence-based quality system
• cf proof capture -- Glitch-to-requirement closed loop
• Quality compounding: every failure becomes a permanent proof obligation
• Run gates from the web UI (backend ready, frontend pending)
• Glitch capture web UI
• Merge gating on PROOF9 pass (web UI)

SHIP (delivery confidence)

• PR status tracking + CI check display in web UI
• Post-merge glitch capture loop

Web UI

• Workspace and PRD views with Socratic discovery, version history, diff/restore
• Onboarding guidance card for new workspaces (Think→Build→Prove→Ship pipeline steps)
• Task board with Kanban, dependency graph visualization, traceability badges, batch execution
• Blocker Resolution view with lifecycle guidance
• Review and Commit view with diff viewer and file tree
• PROOF9 requirements list, detail, evidence history, sort/filter controls, waiver with audit trail
• Interactive Agent Sessions — chat panel (tool calls, thinking blocks), XTerm.js terminal, SplitPane layout
• Run gates button, live gate progress, per-gate evidence display, run history panel (PROOF9 page)
• Glitch capture form and REQ detail view
• PR status panel with PROOF9-gated merge button

---

Configuration

# Required (Anthropic is the default provider)
export ANTHROPIC_API_KEY=sk-ant-...

# Multi-provider LLM (optional — override default Anthropic provider)
export CODEFRAME_LLM_PROVIDER=openai        # anthropic | openai (OpenAI-compatible)
export CODEFRAME_LLM_MODEL=gpt-4o           # model name for the chosen provider
export OPENAI_API_KEY=sk-...                # required when provider=openai
export OPENAI_BASE_URL=http://localhost:11434/v1  # for Ollama, vLLM, LM Studio, etc.
# Per-workspace: .codeframe/config.yaml supports an `llm:` block for the same options

# Optional
export DATABASE_PATH=./codeframe.db         # Default: in-memory SQLite
export RATE_LIMIT_ENABLED=true              # API rate limiting
export RATE_LIMIT_DEFAULT=100/minute        # Default limit

For server configuration, rate limiting options, and API key setup, see docs/PHASE_2_DEVELOPER_GUIDE.md.

Privacy & telemetry

CodeFRAME has opt-in (default off) anonymous telemetry and crash reporting to help us fix beta bugs — command name, duration, exit code, version, and OS only; 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 for exactly what is collected, where it goes, and retention.

---

Testing

# Python / CLI
uv run pytest                          # All tests
uv run pytest -m v2                    # v2 tests only
uv run pytest tests/core/             # Core module tests
uv run pytest --cov=codeframe --cov-report=html   # With coverage

# Web UI (Phase 3)
cd web-ui && npm test                  # Jest unit tests
cd web-ui && npm run build             # Production build verification

---

Documentation

• Product Roadmap -- Current phase plan and feature status
• Vision -- Think → Build → Prove → Ship thesis
• Golden Path -- The CLI-first workflow contract
• CLI Wireframe -- Command-to-module mapping
• Agent System Reference -- Agent components, execution flows
• ReAct Agent Architecture -- Tools, editor, token management
• Phase 2 Developer Guide -- Server layer patterns
• Phase 3 UI Architecture -- Web UI information design

---

Contributing

1. Fork and clone the repository
2. Install dependencies: uv sync
3. Install pre-commit hooks: pre-commit install
4. Run tests: uv run pytest
5. Submit PR with tests and clear description

Code standards: PEP 8, ruff for linting, type hints required, 85%+ test coverage.

During the beta, feature ideas go to Discussions -> Ideas before code. See CONTRIBUTING.md for what's stable, what isn't, and how to propose changes.

---

Security, licensing & support

CodeFRAME is in public beta.

• Security: found a vulnerability? Report it privately via GitHub private vulnerability reporting (or [e-mail]) -- never a public issue. See SECURITY.md for scope and response expectations.
• Licensing: CodeFRAME is AGPL-3.0, an open-core stance. LICENSING.md explains what that means for individuals, internal company use, and embedding -- and how to reach us about commercial licensing or a hosted offering (both planned). Commercial inquiries: [e-mail].
• Early access / design partners: email [e-mail] or reply to the pinned Discussion to be included.
• Help & community: Discussions -> Q&A for questions, Ideas for feature requests, and bug reports for confirmed bugs.

---

License

AGPL-3.0 -- Free to use, modify, and distribute. Derivative works and network services must release source code under the same license. See LICENSING.md for a plain-language explanation and commercial options.

---

Built by Frank Bria

Issues | Discussions | Documentation