firstmate: one agent liaison, a crew of disposable worktrees, and optional persistent secondmates

The tab-juggler problem firstmate attacks

The README describes the pain point precisely: running one coding agent is easy, but three parallel tasks, a fix, an investigation, a plan, turn you into a tab-juggler. You babysit sessions, copy context between repos, and forget which terminal has the failing test. firstmate flips that model. You talk to a single agent, the first mate, and it runs the crew. Each crewmate gets a clean git worktree, works in a visible tmux window, and the first mate supervises to completion. The output is a finished PR, an approved local merge, or a standalone investigation report. This is for engineers who already use a terminal coding agent and want to scale task parallelism without scaling their own attention. It is not for someone who wants a new model or a new CLI; the README states explicitly that firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI. It is an agent distro, a portable directory of instructions and scripts that turns a general-purpose agent into a specialized one.

How the crew is structured: first mate, crewmates, secondmates

The architecture separates roles. The first mate is the single agent you talk to, running in a verified harness like Claude Code, Grok, or Pi. Crewmates are autonomous agents spawned by the first mate, each in its own tmux window or an experimental herdr/zellij tab, and each in a clean treehouse git worktree. The first mate reconciles their output. Two task shapes exist: ship tasks deliver authorized changes, and scout tasks leave standalone investigation reports. Project modes control merge authority: no-mistakes, direct-PR, or local-only, with an optional +yolo flag for merge autonomy. For larger fleets, you can opt in to persistent secondmates. These are still ordinary direct reports, but they run from their own isolated firstmate homes, each with its own FM_HOME, state, projects, and session lock. A secondmate home can live on the same machine or on an SSH-reachable host. The README stresses that a guarded update and recovery path never turns an unavailable remote route into a local replacement. That is a deliberate safety boundary: if the remote secondmate is unreachable, the first mate does not silently substitute a local process.

Event-driven supervision and the zero-token watcher

A key design claim is event-driven, zero-token supervision. A bash watcher sleeps on the fleet and wakes the first mate only when something needs attention. This avoids the common pattern where an agent polls or burns tokens checking status. The watcher is a background process that reacts to events, and it re-arms after each turn. For verified primary harnesses, there is a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live. This matters because agents can stop prematurely, and the backstop catches that. The README gives harness-specific details: Claude Code uses a tracked Stop hook for tokenless watcher re-arm and rewake, Grok uses background-notify wake cycles, and Pi uses its tracked primary watcher extension. Codex and OpenCode are also verified, but they carry more harness-specific supervision tradeoffs. Codex uses bounded foreground checkpoints, and OpenCode uses a TUI plugin. Cursor Agent CLI is verified too, but it requires launching with --trust, and it has no turn-end hook in headless mode. This is a concrete limitation: the zero-token promise depends heavily on which harness you pick, and the README is honest that the three co-primaries are the safest choices.

Install and launch: clone, then let AGENTS.md take over

There is no installer. The README says the cloned repo is the distro. The quick start is: gh auth login, git clone https://github.com/kunchenguid/firstmate, cd firstmate, then launch a co-primary harness. For Claude Code, run claude. For Grok, run grok --trust, and --trust is needed once per clone so project hooks and the turn-end guard load. For Pi, run pi, and approve the project trust prompt once per clone so the tracked .pi/extensions/*.ts files auto-load. There is also a signed-wrapper variant: FM_PI_HARNESS=pi-signed pi-signed. The first mate detects missing tools and offers to install them after you approve. The reference backend is tmux, and you need Git and the GitHub CLI authenticated through gh auth login. This is a low-friction start for someone who already has a terminal agent, but it is a high-context start: AGENTS.md takes over, and you are expected to follow its rules. The README references docs/architecture.md for full detail, but that file is not included in the material I have.

Project boundary and merge authority: who is allowed to touch code

firstmate enforces a strict boundary between the first mate and crewmates. The first mate is read-only over your projects, except for narrow guarded operations approved by the captain, as defined in hard rule 1 in AGENTS.md. One allowed operation is fleet sync's guarded safe branch pruning. Crewmates make every other project change behind the configured merge authority. That means a crewmate can produce a diff, but it cannot merge unless the mode allows it. The +yolo flag grants merge autonomy, which is an explicit opt-in. This design is meant to prevent a supervising agent from making uncontrolled edits while parallel workers operate. The trade-off is that you must trust the AGENTS.md rules to be enforced by the harness, which depends on the harness's hook support. If a harness does not load hooks, such as Cursor Agent CLI without --trust, the boundary may not hold. The README warns that Cursor must be launched with --trust or none of its project hooks load. That is a real failure mode: the safety model is only as strong as the hook mechanism of the chosen harness.

Restart-proof state and the optional Relay for public mentions

All state lives on disk and in the active session backend, which is tmux by default. Kill the session anytime, and the next one reconciles, including confirmed-dead secondmate agents. This is a practical feature for long-running fleets. The README also describes an optional Relay that lets firstmate answer public mentions on X and Discord. It requires a local .env pairing token. Relay actions go through the same lifecycle as chat requests, and it can post up to three public-safe completion follow-ups within seven days. A final reply promised in a thread becomes durable state reconciled from disk, so a restart or a compacted conversation cannot lose it. There is also a dry-run preview that records would-be replies locally before go-live. This is a niche feature, but it shows the project's ambition beyond local terminals. The trade-off is that enabling Relay adds a public-facing surface, which may not be appropriate for every repo.

Limitations: harness lock-in, tmux dependency, and opaque state

The most obvious limitation is that firstmate only works with a specific list of verified harnesses: Claude Code, Grok, Pi, Codex, OpenCode, and Cursor Agent CLI. If you use a different agent, such as a generic OpenAI-compatible CLI or a custom script, firstmate will not supervise it. The README is explicit that these are the supported primaries. Second, the reference backend is tmux. If you are on a system without tmux, or you prefer a different multiplexer, you have to rely on experimental backends like herdr or zellij, and the README says those are experimental or explicitly selected. Third, the state machine is disk-based and opaque to the user. You cannot easily inspect what the first mate is thinking; you only see the tmux windows and the final PRs or reports. For debugging a failed merge, you may need to read the state files yourself. Fourth, the README mentions that Codex and OpenCode carry more supervision tradeoffs, and Cursor has no turn-end hook in headless mode. That means the zero-token promise is not uniform across supported harnesses. If you choose a non-co-primary harness, you may see more token consumption or missed turn-end events.

Alternatives: plain git worktrees vs. a dedicated orchestration layer

The closest alternative is to manage parallel coding agents yourself using git worktree and a terminal multiplexer. Git worktree gives you isolated working directories, and you can manually spawn agents in each one. That approach has no supervision, no merge authority, and no first mate to reconcile outcomes. You would be the first mate. For a small number of tasks, that may be simpler and more transparent. Another alternative is a dedicated orchestration framework like LangGraph or CrewAI, which provide structured agent pipelines. Those are Python libraries, not shell distros, and they require you to write code to define agent roles and transitions. firstmate's approach is different: it encodes the orchestration in AGENTS.md and shell scripts, so the logic is readable and hackable, but it is not a programmable API. If you want fine-grained control over agent communication or complex branching, a code-based framework gives you more flexibility. firstmate is opinionated about the workflow: one liaison, visible crew, disposable worktrees. That is a strength if you agree with the model, and a constraint if you want to customize the protocol.

Maintenance, upgrade cost, and license

The project is MIT-licensed, which means you can modify and redistribute it freely, but the README does not describe a versioning or upgrade mechanism. The repo is a distro, so upgrading likely means pulling the latest commit from the main branch. There are no release notes in the material, and the last push date is unknown. That is a maintenance risk: you cannot know how actively the project is maintained. The README mentions guarded updates for secondmate homes, but that is about updating the secondmate's home, not the firstmate distro itself. The cost of adoption is learning the AGENTS.md conventions and the hard rules. You must trust that the hooks work with your harness version. If a harness updates its hook API, firstmate may break until the project adapts. There is no migration guide in the README. The license is permissive, so you can fork and maintain your own version if the upstream stalls. Before adopting, check the commit history and the last push date on the repository, because the README gives no signal of project activity.

Editorial conclusion

Adopt firstmate if you already live in Claude Code, Grok, or Pi and you routinely juggle three or more coding tasks on the same repo. Skip it if you need a model-agnostic CLI, a GUI, or Windows support. Before adopting, verify that your harness matches the documented setup for turn-end guards, especially if you choose Codex or OpenCode, and confirm that the tmux dependency is acceptable in your environment. The project is MIT-licensed, but the real cost is learning the AGENTS.md conventions and trusting a bash watcher to wake your agent only when needed. If you want parallel work without a supervising agent, a plain worktree manager like git worktree plus your own scripts is simpler.

Official sources

1. Official README
2. Project repository