buildit.ai

AI building AI solutions — so you don't have to.

buildit.ai watches another AI application the way a senior engineer would on launch day — eyes on the UI, reading the logs, spotting what's broken — then rolls up its sleeves and fixes it. Point it at any codebase, walk away, and come back to a cleaner, better-tested product. No humans required (until you want them).

---

Autonomous Software Operator — point it at any Git repo or local project, and it will spin up the full stack, visually inspect it with Playwright, find issues, and optionally apply and validate fixes — all without human intervention.

---

What It Does

Source (Git URL or local path)
        │
        ▼
  Workspace prep        → isolated run directory
        │
        ▼
  Source acquisition    → git clone OR symlink local path
        │
        ▼
  Runtime detection     → language, framework, ports, secrets
        │
        ▼
  App startup           → full stack (Docker Compose, native, or start.sh)
        │
        ▼
  Playwright capture    → screenshots, console errors, network failures
        │
        ▼
  Claude analysis       → structured findings or goal-driven plan
        │
        ▼
  Apply / validate      → code edits committed, app restarted, re-inspected
        │
        ▼
  Artifacts             → report, screenshots, diffs

Three run modes:

Mode	What it does
Inspect	Captures UI state and reports findings — read-only
Apply	Finds issues, generates fixes, applies and validates them
Goal	Iteratively edits code toward a natural-language goal

---

Architecture

buildit.ai/
├── buildit_ai/
│   ├── api/                   FastAPI REST + WebSocket server
│   │   ├── main.py            App entrypoint, CORS, routers
│   │   ├── models.py          Pydantic request/response models
│   │   ├── runner.py          Thread manager: start / cancel / approve runs
│   │   ├── ws_manager.py      WebSocket broadcast to connected frontends
│   │   └── routes/
│   │       ├── runs.py        POST /runs, GET /runs/{id}, POST /cancel, /approve
│   │       ├── ws.py          WS /ws/{run_id}
│   │       └── usage.py       Token usage endpoint
│   │
│   ├── graph/
│   │   ├── workflow.py        LangGraph state machine definition
│   │   └── nodes.py           All graph node implementations
│   │
│   ├── runtime/               Target app startup / teardown
│   │   ├── detection.py       Language/framework/port auto-detection
│   │   ├── base.py            Shared helpers (wait_for_port, build_env, etc.)
│   │   ├── native_runner.py   Runs start.sh / npm / uvicorn inside container
│   │   ├── compose_runner.py  Runs docker compose on host daemon
│   │   ├── docker_runner.py   Single-image container runner
│   │   └── runner_factory.py  Selects the right runner for a profile
│   │
│   ├── inspection/
│   │   └── playwright_runner.py  Multi-page screenshot + error capture
│   │
│   ├── fix/
│   │   ├── claude_builder.py  Inspect-mode fix generation via Claude
│   │   └── goal_agent.py      Goal-mode iterative edit agent
│   │
│   ├── secrets/
│   │   └── manager.py         Auto-discover + merge secrets files
│   │
│   ├── artifacts/
│   │   └── generator.py       Generate findings report + diffs
│   │
│   ├── workspace/
│   │   └── manager.py         Workspace isolation (clone, copy, cleanup)
│   │
│   ├── events.py              Thread-safe event bus (emit → WebSocket)
│   ├── config.py              Central configuration
│   ├── state.py               LangGraph state schema
│   └── cli.py                 Typer CLI entrypoint
│
├── frontend/                  Next.js 15 Mission Control UI
│   └── src/
│       ├── app/page.tsx        Dashboard layout (3-column grid)
│       ├── components/mission/ GoalInput, WorkflowGraph, ContentTabs, etc.
│       ├── hooks/useBuildit.tsx State management + WebSocket integration
│       └── lib/types.ts        Shared TypeScript types
│
├── Dockerfile                 Python 3.12 + Node 20 + Docker CLI + Playwright
├── docker-compose.yml         Three services: buildit (CLI), api, frontend
└── SOURCE_README.md           Integration guide for target projects

---

Quick Start

Prerequisites

• Docker Desktop (with socket access enabled)
• An ANTHROPIC_API_KEY

1. Configure

cp .env.example .env          # if it exists, or create:
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

2. Start the stack

docker compose up --build -d

Service	URL
Mission Control UI	http://localhost:3001
API (REST + WS)	http://localhost:7861

3. Run a mission

Open http://localhost:3001, fill in:

• Source — /path/to/local/project or https://github.com/org/repo
• App URL (optional) — if the app is already running, skip startup
• Mode — Inspect / Apply / Goal
• Goal (Goal mode only) — describe what you want achieved

Click Start Mission and watch the graph.

---

Ports

Service	Host port	Container port
Mission Control UI	3001	3000
buildit.ai API	7861	7861
Target project (standard)	3000	3000

Port 3001 was chosen deliberately to avoid collisions with target projects that typically use 3000.

---

Secrets Management

buildit.ai injects secrets into the target app's environment from three sources (highest priority last wins):

1. Auto-discovered from ~/.buildit-ai/secrets/ — files named {project}.env or {repo-name}.env
2. Per-run override — paste KEY=value lines into the "Secrets / Env Override" panel in the UI
3. Target project .env — loaded from the repo itself

Naming convention

Source type	Secrets file looked up
GitHub org/my-app	my-app.env, org-my-app.env
Local /Users/jb/my-app	my-app.env
Any	default.env (fallback)

Create ~/.buildit-ai/secrets/ and add files there for projects that need API keys not committed to their repos.

---

Runtime Detection

buildit.ai auto-detects how to start a target project:

Signal	Strategy
scripts/start.sh or start.sh	Shell script (recommended for complex stacks)
docker-compose.yml with app service	Docker Compose via host daemon
pyproject.toml / FastAPI	uv run uvicorn …
package.json / Next.js	npm run dev

See SOURCE_README.md for the full guide on making your project work smoothly with buildit.ai.

---

Run Modes in Detail

Inspect

Read-only. Playwright visits every detected page, captures screenshots, console errors, and network failures. Claude generates a structured findings report (severity: critical / high / medium / low).

Apply

Runs inspection, then for each finding above the risk threshold, Claude generates a code fix, applies it to the workspace, restarts the app, and validates the fix with another Playwright pass. High-risk changes require human approval in the UI.

Goal

Given a natural-language goal (e.g. "Fix the broken login flow" or "Add dark mode"), Claude iteratively:

1. Captures the current UI state
2. Analyzes progress toward the goal (confidence score + reasoning)
3. Generates and applies code changes
4. Restarts the app and re-evaluates

Loops until the goal is achieved or max_iterations is reached.

---

WebSocket Events

The frontend subscribes to a per-run WebSocket at ws://localhost:7861/ws/{run_id}. Key event types:

Event	Description
node_started	Graph node began executing
source_acquired	Language/framework/port detected
app_started	Target app is up and healthy
screenshot_captured	Playwright captured a page
finding_detected	A UI/code issue was found
goal_analyzing	Claude is assessing goal progress
goal_analyzed	Confidence score + plan emitted
file_changed	A file was written/modified
approval_needed	Human approval required before applying
run_complete	Run finished (status: done / cancelled / failed)

---

Cancellation

Click Cancel Run in the UI at any time. This:

1. Calls POST /api/runs/{id}/cancel — sets a cancel flag on the backend thread
2. The next events.emit() call inside the graph raises RunCancelledError
3. Any pending approval gate is immediately unblocked (rejected)
4. A run_complete event with status: cancelled is broadcast

---

Development

Backend (Python)

# Install deps
uv sync

# Run API locally (outside Docker)
uv run uvicorn buildit_ai.api.main:app --reload --port 7861

# Lint
uv run ruff check buildit_ai/

# Tests
uv run pytest

Frontend (Next.js)

cd frontend
npm install
NEXT_PUBLIC_API_URL=http://localhost:7861 npm run dev
# Opens on http://localhost:3000

Rebuild Docker stack

docker compose build
docker compose up -d

---

Environment Variables

Variable	Default	Description
ANTHROPIC_API_KEY	(required)	Claude API key
BUILDIT_WORKSPACE	~/.buildit-ai/workspace	Where run workspaces are created
CORS_ORIGINS	http://localhost:3001	Allowed frontend origins
PLAYWRIGHT_BROWSERS_PATH	/ms-playwright	Pre-installed browser binaries
UV_CACHE_DIR	/tmp/uv-cache	uv package cache (writable by non-root)

---

Project Conventions

• Target repos are input, never home — buildit.ai never leaves artifacts inside a target repo
• Workspace isolation — each run gets its own directory under BUILDIT_WORKSPACE
• Non-root container — runs as host UID/GID with supplementary group 0 for Docker socket access
• host.docker.internal — used inside the container to reach services bound to the host machine
• BuildKit required — docker-buildx-plugin is included in the image for projects using advanced Dockerfile syntax