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 Herdr tab, or an experimental 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. This is a concrete limitation: the zero-token promise depends on which harness you pick, and the README names Claude Code, Grok and Pi as equal co-primary recommendations.

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. 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.

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.

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, pi-signed, Oh My Pi (omp), Codex, OpenCode, Cursor Agent CLI, and Antigravity CLI (agy). 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 a Herdr tab or on experimental backends such as Zellij, cmux, Tern, Orca or T3 Code. 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. 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. The repo is a distro, so upgrading likely means pulling the latest commit from the main branch. The repository has no published GitHub releases. The last push was on 2026-11-02, so commits are still landing. 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. The license is permissive, so you can fork and maintain your own version if the upstream stalls. Before adopting, check the commit history on the repository.

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.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases