4x — Multi-Role AI Development Loop

Why 4x?

Single-agent coding is fast but fragile. 4x splits the loop so each role has a focused job, limited scope, and no access to the others' reasoning.

Role Isolation

The Coder never judges its own work. The Reviewer is adversarial by design. No self-review bias.

Crash-Resistant

Everything lives in .4x/ files. Session dies, machine reboots — run picks up exactly where it stopped.

LLM-Agnostic

Switch between Claude, Gemini, Codex, or mix them per role. File-based protocol, no vendor lock-in.

Batch Mode

Dependency-aware scheduling. Queue dozens of features overnight, review them in the morning.

Built for Multi-Repo Projects

Workspace can span multiple independent git repos plus shared hub repos. Every feature runs in its own isolated git worktree — concurrent features never step on each other's files.

Independent Repos, One Workspace

Declare each repo's path and mark shared ones as hub — 4x scopes every feature to only the repos it's allowed to touch.

Git Worktree Isolation

Each feature gets its own linked worktree. No branch switching, no stashing, no collision between features running in parallel.

Scope Guard

Guardrail checks reject any diff that touches a repo outside the feature's declared scope — before it ever reaches review.

$ 4x check my-feature
✗ scope violation: repo "payment" not in feature repos
  feature declares: ["core", "gateway", "web"]
  diff touches:     payment/internal/ledger.go

Every Claim Needs Evidence

Acceptance criteria aren't just checked off — each one must carry evidence in verify.json, and a round the guardrail says is unproven can't be accepted.

AC Evidence Mapping

Every acceptance criterion in verify.json needs a passed flag and an evidence trail. 4x check blocks the round if evidence is missing.

Selective Deep Review

Deep review picks angles based on which files the diff actually touches, instead of running all review angles on every small change.

Cross-Verified Testing

Tester's verify.json results are cross-checked against actual command exit codes — a claimed PASS with contradicting evidence gets caught automatically.

{
  "passed": true,
  "commands": [
    { "command": "make test", "exitCode": 0, "summary": "142 passed" }
  ],
  "ac_results": [
    { "id": "AC1", "passed": true,
      "evidence": ["go test ./internal/guard/... -run TestScopeViolation -v"] },
    { "id": "AC2", "passed": true,
      "evidence": ["make lint: 0 errors"] }
  ]
}

Know What Every Round Costs

The dashboard breaks down token usage and duration per phase, so you see exactly where the budget goes before it surprises you.

Per-Phase Breakdown

Tokens, cost, and duration for designing, coding, reviewing, testing — tracked separately, not just a total.

Model-Aware

Mix opus for design with sonnet for review and test — the dashboard shows the cost impact of each choice.

No Surprises

Runaway rounds show up immediately in the per-phase view instead of hiding in a single end-of-run total.

Per-step model, duration, and cost — no more end-of-run surprises

Cost tracking currently works with the Claude Code runner only (stream-json output) — other runners don't report per-round cost yet.

How It Works

Design

Spec & acceptance criteria

Code

Implement from spec

Review

Adversarial inspection

Test

Verify against criteria

If review or test fails, the loop iterates automatically.

Quick Start

# Install$ brew install ggwhite/tap/fourx
# Initialize in your project$ 4x init
# Create a feature$ 4x new "User authentication with OAuth2"
# Run the AI development loop$ 4x run F001
# Watch it live$ 4x live

Also available via: go install github.com/ggwhite/4x/cmd/4x@latest curl -sSfL .../install.sh | sh

Configuration

Monorepo or multi-repo. Per-role models and instructions. Inject your coding standards, architecture docs, and project rules.

{
  "project": {
    "name": "my-project",
    "language": "go",
    "build": ["make build"],
    "test":  ["make test"],
    "lint":  ["make lint"],
    "docs":  ["docs/architecture/overview.md"],
    "rules": ["always use structured logging"],
    "includes": ["docs/coding-standards.md"]
  },
  "runners": {
    "claude": { "command": "claude", "model": "opus" }
  },
  "default_runner": "claude"
}

{
  "project": { "name": "my-platform" },
  "workspace": {
    "repos": {
      "core":    { "path": "core",    "hub": true },
      "gateway": { "path": "gateway" },
      "admin":   { "path": "admin" },
      "web":     { "path": "web" }
    }
  },
  "runners": {
    "claude": { "command": "claude", "model": "opus" },
    "gemini": { "command": "gemini" }
  },
  "default_runner": "claude",
  "isolation": "worktree"
}

// Per-role model, instructions, and context — tailor each AI agent to your project
{
  "roles": {
    "designer": {
      "model": "opus",
      "instructions": [
        "all specs must define gRPC proto changes before implementation",
        "acceptance criteria must include load test thresholds",
        "always consider backward compatibility with existing clients"
      ],
      "includes": [
        "docs/architecture/service-map.md",
        "docs/api/proto-conventions.md"
      ]
    },
    "coder": {
      "model": "sonnet",
      "instructions": [
        "use dependency injection via dig container",
        "all DB queries must go through repository layer",
        "structured logging only — no fmt.Println",
        "new endpoints must have OpenAPI annotations"
      ],
      "includes": [
        "docs/coding-standards.md",
        "docs/error-handling.md"
      ]
    },
    "reviewer": {
      "model": "sonnet",
      "instructions": [
        "check for SQL injection, XSS, and auth bypass",
        "verify all money calculations use decimal, not float",
        "flag any direct DB access outside repository layer"
      ]
    },
    "tester": {
      "model": "sonnet",
      "instructions": [
        "integration tests must use testcontainers",
        "test concurrent access for all shared state"
      ],
      "screenshot_dir": ".4x/e2e/{feature-id}/screenshot/"
    },
    "deep-reviewer": {
      "model": "opus",
      "parallel_reviewers": 3,
      "max_fix_rounds": 2,
      "includes": [
        "docs/architecture/overview.md",
        "docs/architecture/data-flow.md",
        "docs/security/threat-model.md"
      ]
    }
  }
}

See It In Action

Initialize, create a feature, and start the AI development loop — all from the terminal.

4x Live Dashboard

macOS native (Swift) + Windows / Linux (Tauri). Real-time SSE monitoring, dependency graph, screenshot gallery, 6-language i18n, system notifications.

Per-step model, duration, and cost

Auto-captured screenshot gallery per round

Pick a profile and see the full phase pipeline before running

Supported Runners

Use any AI coding tool. Mix and match per role.

Claude Code

Codex

Gemini

Copilot

Cursor

Antigravity

Self-Evolution

4x learns from its own runs and continuously improves — mining failures, enriching discoveries, gating by value, and iterating itself. When active learnings pass 30, it automatically uses AI to detect semantic duplicates and consolidate them, keeping prompts lean.

History Mining

Extract improvement signals from failed runs, escalations, and recurring FAIL patterns.

Value Gate

ROI evaluation with anti-hack mechanism prevents backlog bloat and low-value work.

Evolve Driver

One command to start the continuous self-improvement loop: mine → evaluate → implement → verify → deploy.