Application map / References / AI coding fleet

The AI Coding Fleet

How Gallopify development is staffed by coding agents: which model does which class of work, how to configure the routing, how to install the platform from the fork, and how pooled subscriptions and quota awareness keep it running.

What the fleet is

Gallopify development runs on a crew of coding agents coordinated by firstmate: one supervising agent per domain (the "first mate") that you talk to, which dispatches autonomous worker agents ("crewmates") per task — each in its own disposable git worktree so parallel work on one repo never collides — supervises them to completion, and hands back finished PRs or investigation reports. firstmate is not an app or a CLI; it is an agent distro — the cloned repo itself (instructions, skills, helper scripts, state conventions) turns a general-purpose terminal agent into the supervisor. The point is throughput without tab-juggling: the human states intent once, decisions escalate upward, and mechanical work fans out to whichever model is best suited to its class.

Which models do what

Work routes by task class, not by availability — a strict preference order per class of work. Availability and quota inform pacing and notifications (see below) but never silently choose the model.

The implementers are Cursor and Codex; Fable is deliberately not the default coder — its quota is reserved for the decisions only it should make. For review, prefer a different model family than the code's author (Codex is the standing review default). When Codex quota runs out, work moves to Claude or Cursor by hand — this failover was exercised live on 2026-09-07.

Where the configuration lives

Three files in the fork carry the routing, from policy to activation:

• docs/routing-policy.md — the human-readable standing policy: the tier table above plus per-task-class preference orders. Edited weekly by hand as model rankings change.
• docs/examples/crew-dispatch.json — the committed template mirroring that policy as machine-readable rules.
• config/crew-dispatch.json — the machine-local activation in each firstmate home (gitignored); the dispatcher actually reads this one. The weekly edit checklist is: edit the policy doc, mirror into the example, copy into each home's config.

Rules are natural-language conditions with an ordered candidate list — the dispatching agent matches the task description against when and tries the use array in order. One real rule from the file:

{
  "when": "The task is design, architecture, product framing, or asking the captain
           clarifying questions: system shape, API boundaries, tradeoff analysis,
           Lavish planning judgment, or Explore-mode hard questions.
           Not bulk implementation.",
  "use": [
    { "harness": "claude", "model": "fable", "effort": "high" },
    { "harness": "claude", "effort": "high" }
  ],
  "why": "Fable owns judgment, design, and architecture. Do not burn Cursor/Codex
          as the first pick for open design decisions."
}

To change what handles a class of work, edit the rule's use order (or add a rule with a more specific when); to change the standing policy itself, start at docs/routing-policy.md and propagate. Note the scope boundary: crew-dispatch only routes when firstmate spawns crewmates (Execute mode). A plain single-agent chat (Explore mode) is not fleet-routed — there the judgment model keeps design questions and delegates mechanical edits to Cursor directly.

Installing from the fork

There is no installer — the cloned repo is the platform. Per the fork's README (linked, not duplicated):

1. Authenticate GitHub: gh auth login (git and the GitHub CLI are the hard requirements, plus tmux as the default session backend).
2. Clone the captain's fork: git clone https://github.com/revvu/firstmate and cd firstmate.
3. Launch a verified primary harness inside the clone — claude (Claude Code) is the usual choice here; Grok and Pi are the other co-primary recommendations. AGENTS.md takes over from there, and the first mate detects missing tools and offers to install them with your consent.

The directory you launched in is now a firstmate home: a self-contained instance carrying its own state, cloned projects, and machine-local config (including config/crew-dispatch.json above). One machine can host several homes — persistent "secondmates" run from their own isolated homes with a separate FM_HOME, locally or on an SSH-reachable host.

Pooled Claude accounts (claude-swap)

Three Claude subscriptions behave as one pooled account. claude-swap (cswap) owns the multi-account inventory and rotates the active login automatically — including underneath running agents, so a Claude agent continues across an account switch without restarting. One Codex subscription and one Cursor subscription complete the fleet.

Because slots rotate automatically, exhausting one slot is a non-event; only the pool matters. That is the captain's operating rule: measure aggregate availability, not per-account state — the platform notifies when the Claude pool crosses a reserve threshold or runs out, and new Claude work pauses for an explicit go-ahead below the reserve.

The moving parts, all in the fork:

• Pool state lives in claude-swap's cache (~/.claude-swap-backup/cache/usage.json): per-slot 5-hour and 7-day usage, Fable share, and disabled flags.
• bin/fm-cswap-pick.sh — a data-only picker that reads that cache and prints the best enabled slot for the need at hand (fable or general).
• config/claude-cswap-auto — when this file is present in a home, spawning a Claude crewmate auto-picks a healthy slot and launches through cswap run <slot>, without changing the captain's own default login. FM_CLAUDE_CSWAP_SLOT=<n> forces a slot for one spawn.

Slot choice is only for Claude crewmates; harness choice (Claude vs Codex vs Cursor) stays with crew-dispatch.

Quota awareness

Dispatch reads current quota windows through quota-axi, which sees the active Claude identity plus Codex and Cursor and publishes, per provider window: percent remaining, runway, and spendPriority. It is deliberately data-only — it never recommends or selects a route.

• runway — whether the window lasts to its refill: through_reset (reaches reset without exhausting), projected_exhaustion (will run dry first, with usable seconds), or exhausted_now (empty). A candidate whose known runway won't cover the task's likely completion is not dispatched, however attractive it otherwise looks — never route into a mid-task stall.
• spendPriority — a signed pace-versus-reset scalar per window: positive means paid allowance is on track to reach its reset unused (headroom worth spending), zero means exactly on pace, negative means overdrawn against the reset clock. Higher is the better place to spend, among candidates already acceptable for the task.

The two rules that bound it

Two honest rules bound all of this. First, the fork's stance (recorded in the Linear project): quota is awareness, not routing — task class picks the model in strict preference order, and quota drives notifications and reserve-threshold pauses. Upstream firstmate's quota-evidence dispatch machinery (the spendPriority ranking) is retained untouched to keep future merges small. Second, and in both worlds: quality class is never silently downgraded to save quota. When every candidate in the strongest reasoning class is tight, the fleet dispatches within that class if any candidate can proceed, or stops and reports — it does not quietly substitute a cheaper model.