What it is
You can run one coding agent easily.
But the moment you want three project tasks done in parallel - fixes, investigations, plans, audits - you become a tab-juggler: babysitting sessions, copy-pasting context between repos, forgetting which terminal had the failing test.
firstmate flips the model.
You talk to a single agent - the first mate - and it runs the crew for you: spawning autonomous agents in a visible session backend, giving each a clean git worktree, supervising them to completion, and handing you finished PRs, approved local merges, or standalone investigation reports.
For larger fleets, you can opt in to persistent secondmates: second mates that are still ordinary direct reports, but run from their own isolated firstmate homes on this machine or another SSH-reachable host.
firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI.
firstmate is an agent distro for running a crew of agents.
An agent distro is a portable directory of instructions, skills, tooling, policies, and state conventions that turns a general-purpose agent into a specialized one.
There is no app to install: the cloned repo is the distro - AGENTS.md, bundled firstmate skills, and helper scripts that any terminal coding agent can follow.
Launching a supported harness inside it for your primary session instantiates your first mate - and makes you the captain.
Features
- One liaison - you talk only to the first mate; it dispatches, supervises, escalates only real decisions, and reports plain outcomes.
- A visible crew - every crewmate works in its own tmux window or Herdr tab, or in an experimental Zellij tab, experimental cmux workspace, experimental Tern block, experimental Orca terminal, or experimental T3 Code thread you can watch or interact with; the first mate reconciles.
- Disposable worktrees - each task runs in a clean treehouse git worktree, or an Orca-managed worktree when
backend=orca, so parallel work on one repo never collides.
- Two task shapes - ship tasks deliver authorized changes; scout tasks leave standalone investigation reports when the intake contract warrants separate research.
- Explicit project modes - each project ships via
no-mistakes, direct-PR, or local-only, with an optional +yolo merge-autonomy flag, an optional branch=<prefix> override for the default fm/ ship-branch prefix, and an optional forge=gerrit binding under which the worker publishes a Gerrit change instead of opening a pull request, plus an optional pr=manual token under which the worker writes the PR title and body instead of the pipeline.
- Self-repo boundary - a home runs as firstmate user/operator by default, so a firstmate bug is diagnosed and patched locally but never pushed, PRed, issued, commented, or forked upstream on its own; publishing to firstmate's own repository needs the
config/firstmate-role maintainer opt-in or a per-task captain consent (schema).
- Optional secondmates - opt in to persistent second mates that run from isolated firstmate homes with their own
FM_HOME, state, projects, and session lock, either locally or as a whole home on an SSH-reachable host, with guarded updates and recovery that never turns an unavailable remote route into a local replacement.
- Event-driven, zero-token supervision - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you; 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.
- Optional Relay - opt in with one local
.env pairing token so firstmate can answer your public mentions on X and Discord alike, 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 without changing non-Relay behavior; a final reply promised in a thread becomes durable state that is reconciled from disk, so a restart or a compacted conversation cannot lose it; dry-run preview records would-be replies and dismissals locally before go-live.
- Strict project boundary - the first mate is read-only over your projects except for the narrow guarded and captain-approved operations authorized by hard rule 1, including fleet sync's guarded safe branch pruning; crewmates make every other project change behind the configured merge authority.
- Restart-proof - all state lives on disk and in the active session backend (see backend selection); the next session reconciles after a restart, while ordinary supervision recovers confirmed-dead secondmate agents without waiting for one.
Full detail on every feature lives in docs/architecture.md.
Quick Start
Requirements
- A verified primary agent harness: Claude Code, Grok, Pi,
pi-signed, Oh My Pi (omp), Codex, OpenCode, Cursor Agent CLI, or Antigravity CLI (agy).
- Git and the GitHub CLI, authenticated through
gh auth login.
- The CLI and dependencies for your selected runtime backend; tmux is the reference default.
The first mate detects supported missing or outdated tools and offers their install or upgrade after you approve.
Backend-specific setup is linked in Documentation.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
