Factor

The autonomous coder. A SOTA coding-CLI orchestrator that fuses frontier models — and lets reality (your tests) pick the winner.

Factor 1.0 · @robomart/factor

For any task, Factor puts the top frontier models in a room, has them debate the approach, generates candidate implementations, runs them against your tests, ships the one that actually passes — and records why. You stop betting on a single model; Factor uses the best of several and proves the result before it lands.

See FACTOR.md for the full thesis, moat, and roadmap.

The loop

task
  → PLAN      one strong model drafts the approach
  → DEBATE    models cross-examine the plan (opening + cross-exam) — no model "winner"
  → FAN-OUT   N diverse frontier models generate candidate diffs in parallel
  → EXECUTE   run each candidate against tests / typecheck / lint / build (sandboxed worktree)
  → SELECT    keep what passes; tie-break on coverage + smallest diff
  → REPAIR    feed failures back to the closest candidate; loop until green or budget hit
  → COMMIT    apply the winning diff + write the decision record (DECISIONS.md) and git-commit

Why this beats the alternatives: cross-examination makes the work better (not just selected, à la blind "fusion"), and the test suite is the judge — which kills both the biased-arbiter problem and pure-debate herd consensus.

Install

curl -fsSL https://factor.ac/install.sh | sh

Then, inside any git repo with a provider key set:

factor "add input validation to the signup handler"

You only need one working provider key — the layer (vendored from Meter) tries direct keys → Bedrock → OpenRouter → auto-route. OPENROUTER_API_KEY alone covers every model. Requires bun (the installer adds it if missing).

bun install
cp .env.example .env
bun run bin/factor.tsx "fix the failing test in cart.test.ts"

Usage

factor [run] "<task>" [options]

  -y, --yes              Apply & commit the winner without prompting
  -c, --candidates <n>   Candidates to fan out (default 3; the router may lower it)
      --no-debate        Skip cross-examination
      --budget <usd>     Hard $ ceiling (or FACTOR_BUDGET_USD)
      --model <ids>      Comma-separated panel override (OpenRouter ids)
      --plan-model <id>  Model that drafts the plan
      --plain            Force the plain (non-TUI) renderer

Factor runs in your git repo. It operates from HEAD, sandboxes every candidate in a throwaway git worktree (your working tree is never touched until you approve), commits the winner locally, and does not push — that stays your call.

What's where

| Path | Role | |---|---| | src/providers/ | Provider + pricing layer vendored from Meter (fallback.ts, models.ts) — multi-tier fallback across 5 providers, cache-aware cost. | | src/core/ | turn (metering primitive), plan, debate, fanout, protocol (file-block output). | | src/harness/ | exec (sandboxed runner), repo (context + command discovery), worktree (per-candidate sandboxes). | | src/verifier/ | gate runner (tests/typecheck/lint/build) + testgen (impartial shared suite when a repo has none). | | src/selector.ts · src/repair.ts · src/router.ts · src/record.ts | select winner · repair loop · difficulty gate · decision record + commit. | | src/loop.ts | the orchestrator. | | tui/App.tsx · bin/factor.tsx | Ink TUI · CLI entry (TUI on a TTY, plain renderer when piped). |

Verifier & repos without tests

The test suite is the judge, so a repo needs something to run. When no tests exist, Factor generates an impartial suite once (from the task + plan, not from any candidate's code) and runs that same suite against every candidate — generated tests are surfaced and committed alongside the diff, never hidden. Generated-test quality bounds correctness, so review them. Best results today are on repos that already have a test script.

Dev

bun run typecheck            # tsc --noEmit
bun run scripts/smoke-offline.ts   # offline integration test (no API keys, no spend)

The offline smoke test exercises the full spine — worktree sandboxing, real gate execution, diff, selector, repair-targeting, protocol safety — without any model calls.

Status

v0.1 — proves the thesis: fused, verified, remembered. Gating, the full repair loop, and a credits backend are roadmap (see FACTOR.md).