kunchenguid/firstmate: an agent distro for running a crew of coding agents

The tab-juggling problem firstmate is built around

Running one coding agent is easy. Running three tasks in parallel in the same repository is not. The README describes the failure mode precisely: you become a tab-juggler, babysitting sessions, copy-pasting context between repos, and forgetting which terminal had the failing test.

The audience is therefore narrow and specific. firstmate is for engineers who already work inside a terminal coding agent and who have started running more than one at a time. It assumes Git, an authenticated GitHub CLI, and a willingness to let a supervising agent dispatch work on your behalf. If you run one task at a time and finish it before starting the next, the coordination layer has nothing to coordinate.

The project also draws a boundary that matters for evaluation. The README states that firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI. It calls itself an agent distro: a portable directory of instructions, skills, tooling, policies, and state conventions that turns a general-purpose agent into a specialized one. That framing explains almost every design decision below, including why there is nothing to install.

One liaison, disposable worktrees, and where state lives

The architecture is a star topology with a human at one end. You talk to the first mate. The first mate dispatches to crewmates, supervises them, escalates only real decisions, and reports plain outcomes. Crewmates work in visible session backends: a tmux window each, or an experimental herdr or zellij tab, or a cmux workspace, or an Orca terminal. You can watch or type into any of them. The first mate reconciles what it sees.

Isolation comes from git worktrees. Each task runs in a clean treehouse worktree, or an Orca-managed worktree when `backend=orca`, so parallel work on one repository never collides. This is the part that removes the copy-paste step: separate tasks get separate checkouts rather than sharing a working directory.

Tasks come in two shapes. Ship tasks deliver authorized changes. Scout tasks leave standalone investigation reports when the intake contract warrants separate research. That distinction is worth reading carefully before you dispatch anything, because a scout task will not produce a branch for you to merge.

Supervision is event-driven rather than polling. A bash watcher sleeps on the fleet and wakes the first mate only when something needs you, which the README describes as zero-token supervision. Verified primary harnesses also get a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live. All state lives on disk and in the active session backend, so killing the session does not lose the fleet; the next session reconciles and carries on.

Installing firstmate and launching a first mate

There is no package to install. The README says the cloned repository is the distro: `AGENTS.md`, bundled firstmate skills, and helper scripts that any terminal coding agent can follow. Launching a supported harness inside that directory instantiates your first mate.

Requirements are a verified primary agent harness (Claude Code, Grok, Pi, `pi-signed`, Codex, OpenCode, or Cursor Agent CLI), Git and the GitHub CLI authenticated through `gh auth login`, and the CLI and dependencies for your selected runtime backend, with tmux as the reference default. The README notes the first mate detects and offers to install supported missing tools after you approve.

The install is three commands. The first authenticates the GitHub CLI, which the crew needs in order to open pull requests on your behalf.

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

After that, launch one of the co-primary harnesses from inside the directory. Claude Code needs no extra flag:

claude

Grok needs `--trust` once per clone so that project hooks and the turn-end guard load. The README notes that `/hooks-trust` inside Grok also works:

grok --trust

Pi needs you to approve the project trust prompt once per clone on first launch, so that the tracked `.pi/extensions/*.ts` files auto-load. The signed wrapper is a distinct identity, selected through an environment variable:

pi
# or, when the signed wrapper is installed
FM_PI_HARNESS=pi-signed pi-signed

What you should see after launching is a first mate session that reads `AGENTS.md` and takes over from there. The README does not document a first-run walkthrough beyond that point, so treat the initial session as the place where project modes and merge authority get set.

Project modes, merge authority, and the read-only boundary

Each project ships through one of three modes: `no-mistakes`, `direct-PR`, or `local-only`, with an optional `+yolo` flag that grants merge autonomy. This is the control surface that decides how much a crewmate can do without asking you.

The boundary around the first mate itself is stricter than around the crew. The README describes a strict project boundary in which the first mate is read-only over your projects except for narrow guarded and captain-approved operations authorized by hard rule 1 in `AGENTS.md`, including guarded safe branch pruning during fleet sync. Crewmates make every other project change behind the configured merge authority.

That split is the design's most opinionated choice, and it has a cost. Anything that needs the first mate to touch a repository outside those guarded operations has to go through a crewmate, which adds a hop. The payoff is that a misbehaving supervisor cannot rewrite your working tree directly. Whether that trade is worth it depends on how much you trust the dispatch logic versus how much you trust the individual crewmate tasks, and the README does not offer a way to loosen the first mate's boundary without editing the distro.

Secondmates, Relay, and the limits of the documented surface

Two features are opt-in and change the operational shape of a deployment.

Secondmates are persistent second mates that are still ordinary direct reports but run from their own isolated firstmate homes, with their own `FM_HOME`, state, projects, and session lock. They can run locally or as a whole home on an SSH-reachable host. The README states that guarded updates and recovery never turn an unavailable remote route into a local replacement. That last clause is the interesting one: if the remote host goes away, firstmate will not silently substitute a local home for it. The failure is visible rather than masked, which is the right default for a fleet that spans machines, but it also means an unreachable host leaves that part of the fleet unavailable until it returns.

Relay is the other opt-in. A single local `.env` pairing token lets firstmate answer public mentions on X and Discord, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days for genuine milestones and the final outcome. The README says non-Relay behavior is unchanged. A final reply promised in a thread becomes durable state reconciled from disk, so a restart or a compacted conversation cannot lose it, and a dry-run mode records would-be replies and dismissals locally before go-live. Anything that turns a coding agent into a public-facing responder deserves the dry run first; the README provides one, and skipping it would be the wrong call.

Where the documentation thins out: the README mentions no releases, so there is no changelog to read for upgrade impact. It does not document rollback for a distro update. It also does not state a last-push date, so anyone evaluating maintenance cadence should check the repository directly rather than assume a schedule.

What firstmate does not do, and what to compare it against

The clearest limitation is the harness dependency. firstmate does not run without a verified primary agent harness, and the README ranks them. Claude Code, Grok, and Pi are equal co-primary recommendations with verified turn-end guard paths when launched with their documented setup. Codex and OpenCode are verified and supported but carry more harness-specific supervision tradeoffs: Codex uses bounded foreground checkpoints and OpenCode uses a TUI plugin. Cursor Agent CLI is verified as a primary using a tracked project-scope `.cursor/hooks.json` whose `stop` hook parks on the watcher between turns, but it must be launched with `--trust` or none of its project hooks load, and it has no turn-end hook in headless `cursor-agent -p`, so the primary session has to run interactively.

That means firstmate is the wrong tool if you want a headless, unattended pipeline. The supervision model assumes an interactive session you can watch and type into, and the harnesses with the weakest guard paths are exactly the ones you would reach for in a headless setup.

A fair alternative to compare against is a plain multi-worktree workflow: you create `git worktree` checkouts yourself and run one agent per checkout in separate tmux windows. The difference in approach is who holds the coordination state. In the manual version, you are the reconciler: you remember which window has the failing test, you decide when a task is finished, and you move context between checkouts by hand. firstmate moves that reconciliation into a supervising agent with on-disk state and an event-driven watcher, and adds the dispatch, escalation and merge-authority layers on top. If your tasks are few and long-running, the manual version is less machinery. If they are numerous, short, and interleaved, the coordination layer is the whole point.

Licence and upgrade cost

firstmate is MIT licensed. In practical terms that permits use, modification, and redistribution with the licence and copyright notice retained. This is not legal advice; if you plan to redistribute a modified distro, read the `LICENSE` file in the repository and get your own counsel.

Because the cloned repository is the distro, upgrading is a git operation on your working copy rather than a package manager transaction. That has a consequence the README does not spell out: local edits to `AGENTS.md`, the bundled skills, or the helper scripts in `bin/` will conflict with upstream changes, and the README does not document a rollback path for a distro update. The `CONTRIBUTING.md` file in the repository is the place to look for how the maintainers expect changes to flow. If you intend to customize the distro, keep your changes in a branch and expect to rebase rather than pull.

Editorial conclusion

Adopt firstmate if you already run Claude Code, Grok or Pi interactively and your bottleneck is coordinating several tasks in one repository rather than writing code. Do not adopt it if you want a single packaged binary, if your harness is not on the verified list, or if you cannot tolerate tmux as the reference session backend. Before committing, verify three things: that `gh auth login` succeeds in the environment where the first mate will run, that your chosen harness is one of the three co-primaries with a verified turn-end guard path, and that you are comfortable with the project boundary described in AGENTS.md hard rule 1, since the first mate is read-only over your projects apart from the narrow guarded operations that rule authorizes.

Frequently asked questions

Official sources

1. Official README
2. Project repository