Firstmate: Talk to one agent. Ship with a crew

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.

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 instantiates your first mate - and makes you the captain.

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, experimental herdr/zellij tab, cmux workspace, or Orca terminal you can watch or type into; the first mate reconciles.Disposable worktrees- each task runs in a cleantreehousegit worktree, or an Orca-managed worktree whenbackend=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 viano-mistakes

,direct-PR

, orlocal-only

, with an optional+yolo

autonomy flag.Optional secondmates- opt in to persistent second mates that run from isolated firstmate homes with their ownFM_HOME

, state, projects, and session lock, supervising project clones or a project-less firstmate-repo domain, kept on the primary firstmate version by guarded local fast-forwards and checked for live agent processes at session start.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 X mode- opt in with one local.env

token so firstmate can answer your public@myfirstmate

mentions, 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-X 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 byhard 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 (tmux by hard default, herdr or cmux when selected or auto-detected, zellij/orca when explicitly selected); kill the session anytime and the next one reconciles, including confirmed-dead secondmate agents, and carries on.

Full detail on every feature lives in docs/architecture.md.

• A verified primary agent harness: Claude Code, Grok, Pi, pi-signed

, Codex, or OpenCode. - 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 and offers to install supported missing tools after you approve. Backend-specific setup is linked in Documentation.

Claude Code, Grok, and Pi are equal co-primary recommendations for running the primary firstmate session, with pi-signed

supported as Pi's distinct signed-wrapper identity. 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. All three have verified turn-end guard paths when launched with their documented setup. Pick whichever one matches your subscription and workflow.

Codex and OpenCode are also verified and supported as primary harnesses; Codex uses bounded foreground checkpoints, and OpenCode uses a TUI plugin, so both carry more harness-specific supervision tradeoffs than the three co-primaries.

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

Then launch one of the co-primary harnesses; AGENTS.md takes over from there:

Claude Code

claude

Grok

grok --trust

Pi

pi
FM_PI_HARNESS=pi-signed pi-signed

For Grok, --trust

is needed once per clone so project hooks and the turn-end guard load; /hooks-trust

inside Grok works too. For Pi, approve the project trust prompt once per clone on first launch so the tracked .pi/extensions/*.ts

files auto-load. Pi's /calm

toggle hides supported transcript chrome, including canonically classified Firstmate operational user rows, and uses a Calm-only animated working boat during active runs while preserving all model context and session data. The hidden operational inputs remain ordinary user-role messages with unchanged delivery, ordering, authority, persistence, and exports. The preference persists for the effective Firstmate home, and toggling it off restores ordinary rendering. Calm's current behavior and supported limits are separate from its version-scoped maintainer evidence.

> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode


  PR ready for review, captain: https://github.com/you/xyz/pull/42
  (fix flaky login test - risk: low - CI green)

> alright merge it

Setup guides for tmux (the default) and every other supported backend (herdr, zellij, Orca, cmux) are linked in Documentation below.

            you (the captain)
                  │  chat: requests, decisions, "merge it"
                  ▼
 ┌─────────────────────────────────────┐
 │ firstmate            (this repo)    │
 │ reads projects/ + firstmate routes  │
 │ writes guarded backlog/briefs/state │
 └──┬──────────────┬───────────────┬───┘
    │ backend sends / status files │
    ▼              ▼               ▼
 ┌────────┐   ┌────────┐      ┌────────┐
 │fm-task1│   │fm-task2│  ... │fm-taskN│   tmux windows, herdr/zellij tabs, cmux workspaces, or Orca terminals
 │crewmate│   │crewmate│      │crewmate│   one autonomous agent each
 └───┬────┘   └───┬────┘      └───┬────┘
     ▼            ▼               ▼
  treehouse worktree, Orca worktree, or isolated secondmate home
     │
     ├─ ship: project mode ► PR/local merge ► teardown
     │
     └─ scout: report at data/<id>/report.md ► decision inventory ► relay findings ► teardown

You chat with the first mate. It routes each request to a crewmate in its own session endpoint and git worktree, supervises the fleet with a zero-token event-driven watcher, and brings you finished PRs, approved local merges, or investigation reports. Optional secondmates extend this to persistent second mates, dispatch profiles let you steer which harness handles which task, and an opt-in X mode lets the same fleet answer public mentions. codex-app

is not a runtime backend yet; docs/codex-app-backend.md owns the Codex App boundary.

Full architecture - the supervision engine, worktree isolation, secondmates, dispatch profiles, project modes, optional X mode, fleet sync, and self-update - is in docs/architecture.md.

Firstmate ships these user-invocable built-in skills. Claude and grok use the slash form shown here; codex uses the same names with $

, such as $afk

.

Skill	What it does
/afk
Enter away-mode supervision: the sub-supervisor self-handles routine notifications in bash, escalates captain-relevant events and bounded declared-external-wait rechecks as batched digests, and actively alerts if delivery gets stuck while you step away
/ahoy
Recap visible session events since the prior real captain message plus visibly unanswered captain decisions, falling back to Bearings when invoked as the session's first real captain message
/bearings
Generate a concise four-section chat digest from bounded local fleet and registered-secondmate state; use /bearings file to also replace today's dated report in data/ , and add include PRs when live PR enrichment is wanted
/updatefirstmate
Self-update the running firstmate and its secondmates to the latest from origin with fast-forward-only pulls, then re-read instructions and nudge secondmates
/stow
Sweep the session for uncaptured durable knowledge, route each finding to its disk home per AGENTS.md, file undone next steps to the backlog, and report what is now safe to reset

Bearings invocation examples:

/bearings

returns the fresh four-section digest in chat only./bearings include PRs

keeps chat-only mode and opts into live PR enrichment./bearings file

replaces today'sdata/status-report-<YYYY-MM-DD>.md

from scratch and links it from the four-section chat digest./bearings file include PRs

combines the dated report with live PR enrichment.

Agent-only reference skills live under .agents/skills/

and are loaded by firstmate at the trigger points named in AGENTS.md.

Firstmate's skills live in two separate places with different audiences:

.agents/skills/

• agent-loaded skills (this section's table, plus firstmate's agent-only reference skills). Every one of these assumes a live firstmate home and is meaningless, or actively misleading, installed anywhere else, so each carriesmetadata.internal: true

in its frontmatter. That flag hides them from installer discovery (tools like theskills.shnpx skills add

installer) without affecting how firstmate itself loads them - frontmatter metadata is inert to the agent's own skill .skills/

• public, installer-facing skills meant to be installed standalone into any project, independent of firstmate. Each one is a self-contained skill with no dependency on firstmate's paths, tools, or vocabulary. Today that isskills/stow

, a generic session-knowledge-sweep skill that routes findings by explicit instruction first, then existing local conventions, then a private.stow-notes.md

fallback in the current directory, and closes with a resume pointer for the next session. It intentionally shares no code with the firstmate-internal.agents/skills/stow

it is named after, so the two can evolve independently.

docs/architecture.md- maintainer architecture for the crew, supervision, worktrees, secondmates, and project modes.docs/configuration.md- environment variables,FM_HOME

, runtime backend selection, optional X mode, the files you set, and harness support.docs/calm.md- current Pi/calm

behavior and supported presentation limits.docs/wedge-alarm.md- configure the active alert for an away-mode escalation delivery that gets stuck.docs/tmux-backend.md- current setup and limits for the tmux reference backend.docs/herdr-backend.md- current setup, safety boundaries, and limits for the experimental Herdr backend.docs/zellij-backend.md- current setup and limits for the experimental Zellij backend.docs/orca-backend.md- current setup and limits for the experimental Orca backend.docs/cmux-backend.md- current setup, socket security, and limits for the experimental cmux backend.docs/codex-app-backend.md- the current blocked Codex App backend boundary and rollout contract.docs/verification/runtime-backends.md- active maintainer verification for runtime backend guarantees.docs/gitlab-merge-watch.md- maintainer verification for GitLab merge watching on arbitrary instances.docs/turnend-guard.md- the primary session's current "no turn ends blind" backstop, scope, loop safety, and compatibility limits.docs/verification/supervision.md- active maintainer verification for session-start, guard, continuity, and wedge integrations.docs/supervision-protocols/- rendered primary-harness watcher protocols for Claude, Codex, OpenCode, Pi andpi-signed

, Grok, and unknown harness fallback.docs/scripts.md- thebin/

toolbelt reference.docs/documentation-audiences.md- documentation audiences and the machine-checked placement boundary.- the distro's always-loaded operating contract and routing index for conditional procedures.AGENTS.md

CONTRIBUTING.md- how to contribute, including the dev/test commands.

Contributions are welcome - see CONTRIBUTING.md for the workflow, repo conventions, and how to run the tests.

MIT - see LICENSE.

source & further reading

github.com — original article