Fagan

Fagan

Spend tokens on judgment, not typing.

*A real story (STE-1, PR #986) crossing the board: implemented by an open-weight model, sent back once by review, merged. 14 minutes, time-lapsed.*

Try it (macOS; Linux via Ollama or LM Studio), then see the Quickstart:

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

Frontier models cost money per token and are excellent at judgment. Local models run free and are adequate at typing. This pipeline splits software engineering along exactly that line: a frontier model decomposes the work, plans it, reviews the diff, and adjudicates anything risky — while a local model writes the implementation at no marginal cost.

What makes the cheap half trustworthy is inspection. In Michael Fagan's 1976 IBM study, formal inspection found 82% of the defects in the released product — 38 per KLOC, against 8 per KLOC for unit testing. Quality lives in the gate, not in the author. So this project spends its budget on gates: TDD enforced before implementation, an independent review pass, acceptance-oracle grading, a risk-tiered overlord that stops for a human on anything irreversible, and a merge gate that re-runs the suite against the rebased branch before anything lands.

The goal is narrow and specific: enterprise-grade engineering discipline — decomposition, TDD, code review, dependency-ordered delivery — on a $20/month budget.

For detailed reference material, see REFERENCE.md.

Before you start: read Reliability & limitations below. This is an autonomous coding pipeline with real, documented failure modes — it is not a hands-off "describe a feature, get a PR" tool yet.

Platform support

Developed and run day-to-day on macOS. The core (MCP server, dashboard, Claude-backend dispatch/review, the full test suite) is plain Python and CI tests it on Ubuntu across Python 3.11–3.14 on every pull request and push, plus macOS on 3.14 on every push to master and nightly. Two pieces are macOS-only:

• **launchd/*.plist** — the scheduler/MLX-supervisor/usage-poller are packaged as launchd jobs on macOS. On Linux, render the systemd equivalent with scripts/generate_systemd_units.sh (see Scheduler below) instead of hand-rolling init files, or run the entry points directly in a foreground terminal/tmux session.
• MLX (PIPELINE_LOCAL_PROVIDER=mlx) — Apple Silicon only. Local dispatch works fine on Linux via Ollama or LM Studio instead (PIPELINE_LOCAL_PROVIDER=ollama / lmstudio).

Windows is untested.

Quickstart

One-line install

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

This clones the repo to ~/.fagan (override the location with FAGAN_INSTALL_DIR, and the source URL with FAGAN_REPO_URL) and runs scripts/install.sh inside it -- equivalent to the manual clone-and-run steps below, minus the typing. Re-running it later updates the existing checkout (git pull --ff-only) instead of re-cloning.

Piping a remote script into bash means trusting whatever that URL serves at fetch time. If you'd rather read it first:

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh -o remote-install.sh

less remote-install.sh # or open it in an editor bash remote-install.sh

Either way, cd into the install directory it reports (~/.fagan by default); it has already done steps 1–3 below, so restart Claude Code (step 5). Prefer a manual clone? Use the steps below instead.

This gets the MCP server registered and a first plan running end-to-end. A first run needs no local model at all: with nothing configured, dispatch and review fall back to the claude backend, which shells out to the Claude Code CLI. That fallback is the *starting* configuration, not the intended one — the cost split described above only happens once you deliberately route the implementation role to a local model, which is why the shipped registry ships no roles block of its own: see Provider selection & authorization below for how to make that choice when you're ready.

# 1. Clone and install the Python environment

git clone https://github.com/motock/fagan.git cd fagan scripts/install.sh # creates .venv, installs requirements.txt

2. Register the MCP server with Claude Code (adjust the path to where you cloned it)

claude mcp add -s user pipeline "$(pwd)/.venv/bin/python3" "$(pwd)/app/pipeline_mcp_server.py"

3. Copy the persona subagents and decision policy into place

(cp -n skips any file you already have — e.g. a customized code-reviewer.md —

instead of silently overwriting it; diff before removing -n if you do want the update)

mkdir -p ~/.claude/agents cp -n agents/*.md ~/.claude/agents/ cp -n overlord-policy.md ~/.claude/overlord-policy.md

4. (Optional) Install the global rules bundle for your agent CLIs

scripts/install_global_rules.py --tools=claude,codex,opencode

Opt-in: nothing is written unless --tools is passed. It writes the bundle into

~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md, copies

the rule files into the sibling fagan-rules/ directory, and backs up an existing

file as .fagan-bak- . Re-running refreshes only the fenced

block between the fagan:begin and fagan:end markers.

5. Restart Claude Code (or start a new session) so it picks up the MCP server

scripts/install.sh creates the .venv, installs requirements.txt and requirements-dashboard.txt (the dashboard's fastapi/uvicorn deps, installed on every run; a --dev install uses requirements-dev.txt, which already includes the dashboard deps), and reports on the tools the pipeline shells out to — required: git, gh, and the claude CLI; optional: ollama and docker — with graceful-degradation messaging, and is safe to re-run. It does not register the MCP server, set environment variables, or install the persona subagents — steps 2–3 above cover those. With nothing but the claude backend configured, ollama/docker being absent is expected, not an error.

From a Claude Code session in the project you want the pipeline to work on:

1. Ask the product-analyst subagent to turn a goal into epics/stories, or hand-write a plan per the schema.
2. mcp__pipeline__save_plan (or ingest_plan) with that plan and a repo_root pointing at the target project — not this pipeline repo.
3. mcp__pipeline__list_ready_stories to see what's unblocked, then mcp__pipeline__dispatch_story to claim and start one.
4. Watch progress with the dashboard: scripts/dashboard.sh start, then open http://localhost:8000.
5. For unattended operation, run the scheduler so ready stories advance without you calling advance_pipeline by hand: .venv/bin/python3 -m pipeline.scheduler_daemon (foreground, or under launchd/systemd/tmux — see Scheduler below).

Start with PIPELINE_AUTONOMY=dry-run (plans and logs only, nothing is dispatched or merged) until you've watched one plan run and trust the gates — see Autonomy levels.

Only using the `claude` backend? The PIPELINE_LOCAL_* and PIPELINE_BACKEND_*=ollama/lmstudio/mlx variables, and Ollama/MLX/LM Studio setup, only matter if you opt a role into local-model dispatch — but provider selection itself is still a required setup step (the shipped registry routes nothing; see Provider selection & authorization below), and even the claude path needs two credentials before the first dispatch: gh auth login (the pipeline opens and merges PRs through the GitHub CLI) and the Claude Code CLI's own login. See Minimal configuration for the handful of variables actually worth setting on day one, versus the ~100 that exist purely for tuning.

Provider selection & authorization

Provider selection is a required setup step. The shipped model_registry.json deliberately declares which models exist per provider but ships no `roles` routing: this project decouples from any single provider, so the operator chooses. There are two supported ways to select a provider per role, checked in this order by resolve_role:

1. Plan role config — a plan's per-role provider/model beats everything below.
2. A `roles` block in a registry file — the single source of truth for role routing; see below.
3. `PIPELINE_BACKEND_ ` environment variables — consulted only when the registry has no entry for the role (the empty-state path, so a fresh clone still boots); e.g. PIPELINE_BACKEND_DISPATCH=ollama opts the dispatch role into Ollama.
4. The caller's own fallback — for dispatch/review this is the claude backend.

For an interactive alternative to editing registry JSON by hand, run the picker: .venv/bin/python scripts/choose_providers.py. It walks through all nine roles one at a time, showing each role's current provider/model and where that setting came from, and lets you switch it by typing an option number — each of the nine roles is configured independently, and every change is validated against the registry before it is written. It is safe to re-run any time: re-running just re-reads the current routing, and pressing Enter keeps a role's existing setting.

The same two registry files work for both selection styles:

• `PIPELINE_MODEL_REGISTRY_PATH` points the pipeline at any registry JSON you like.
• `model_registry.local.json` (repo root) is the convention for a personal registry: it is gitignored, so your per-role routing stays out of the repo. Point PIPELINE_MODEL_REGISTRY_PATH at it, or copy it over model_registry.json locally if you prefer not to set the variable.

A roles block names a provider and a *friendly* model name per role; the friendly name must exist under that provider's models in the same file, and the concrete tag is resolved from there. A typo raises an error rather than silently falling back.

Authorization matrix. Selecting a provider also selects which credentials you must establish first — scripts/install_checks.py probes these and reports unauthorized (remedy: a login, not an install) where it can:

On the :cloud rows: those calls are proxied through https://ollama.com by the local ollama daemon, which sends its own credential — the pipeline sends no credential of its own. :cloud tags ar