Concepts & vocabulary

The crew metaphor is load-bearing. Learn the six roles, the two task shapes, and the six rules in VISION.md that decide every design question.

The roles#

Term	What it is
Captain	You, the human. The first mate must say "captain" at least once in every chat reply, bad news included (`AGENTS.md`). It never puts that address into commits, PRs or code.
First mate	The primary agent session. It is any supported harness launched inside the cloned repo. `AGENTS.md` is "your entire job description". It plans, dispatches, supervises and reports. It never does project work itself.
Crewmate	An autonomous worker spawned for one task, in its own worktree and its own terminal window or tab. It is disposable: when the work lands, it is torn down. It never addresses you.
Secondmate	"A crewmate with an isolated firstmate home and a charter, not a second architecture." It is persistent, has its own `FM_HOME` (state, backlog, projects, lock) and a routing scope, and can live on another machine over SSH. It sits idle until work is routed to it.
Fleet	Everything under one first mate: crewmates, secondmates, tasks, backlog.
Home (`FM_HOME`)	One firstmate instance's private `data/`, `state/`, `config/` and `projects/`. The scripts always come from the tracked checkout. A secondmate is simply another home.

Where 'crewmates' mean something else

GROK_BOT.md describes a different deployment: a Grok Bot whose "crewmates" are persistent role bots (inbox, research, documents). That is the social-bot incarnation of the same pattern. The CLI distro in AGENTS.md, which this guide covers, uses throwaway worktree workers.

Two task shapes#

Ship (the default) produces a change to a project. The change is delivered through the project's delivery mode: a PR through no-mistakes, a direct PR, or a local fast-forward merge.

Scout produces knowledge only: data/<id>/report.md, never a PR. Use it for investigation, diagnosis, planning, reproduction and audits, when you ask for a separate report or when uncertainty could change whether to build. A scout can later be promoted in place to a ship task (bin/fm-promote.sh). It keeps its context, and a reproduced bug becomes the regression test.

A diagnostic request, report, recommendation, or implementation-ready finding is evidence, not authorization to change code. — AGENTS.md §7

"Agent distro"#

Kun settled on this name in July 2026:

it's not a harness... it's also not a skill... and it's obviously also not a model, not a CLI, and not a MCP. i call it an 'agent distro' because i feel it's closest analogy is a linux distro. — @kunchenguid, 2026-07-12

The distro is a directory:

AGENTS.md — the supervisor contract, capped at 9,000 words. CLAUDE.md is a pointer to it.
.agents/skills/ — skills loaded at trigger points. .claude/skills is a symlink to this.
bin/ — about 200 bash scripts that own every exact mechanic.
Harness hook files: .claude/settings.json, .pi/extensions/, .omp/extensions/, .cursor/hooks.json, .codex/hooks.json, .opencode/plugins/, .grok/hooks/.
Private, gitignored state: data/, state/, config/, projects/, .env.

Because everything is plain text and bash, the first mate can read and change itself. Kun says this is why most of firstmate is bash rather than harness hooks:

most things firstmate does is in plain bash scripts. biggest benefit is if something doesn't work well, the agent can fix things by itself. if done with hooks or those harness specific features often times it can't be modified on the fly without restarting the harness. — @kunchenguid, 2026-06-30

The six rules in VISION.md#

Every behaviour in the repo traces back to one of these. When firstmate does something that surprises you, one of these is usually the reason.

1. One captain, one interface#

You talk only to the first mate. Workers report only through it. Captain-facing language is "outcomes, consequences, and decisions; the machinery that produced them stays below deck." An escalation exists only for a decision a human must make. Progress and retries are never news.

2. Authority is explicit and never inferred#

"The captain is the default authority for every gate." Autonomy is an explicit grant, per project, and it "never quietly widens".
Merging, discarding work, and anything destructive, irreversible or security-sensitive need your explicit word.
"Evidence is never authorization."
The first mate never does the work itself: "even the smallest change is a worker's job, because trivial is a guess and command attention does not scale."

3. Scripts own the mechanics, agents own the judgment#

Exact logic lives in deterministic scripts. Understanding lives in agents. "The two never mix."
Token efficiency is first-class. The command structure stays flat, because every extra layer costs fidelity and tokens.

4. A restart is a non-event#

Work in flight, promises made, open decisions and your preferences all live in durable records on disk. Kill any session, including the first mate's own, and nothing is lost. This rule came from a real incident:

once upon a time i was working with ~10 agents in tmux... i walked away to make coffee. when i came back, the screen showed an empty terminal... my 'agent civilization' just got a team wipe... this team wipe led to me putting down a founding principle in firstmate - restart should be a non-event. — @kunchenguid, 2026-08-31

5. Delegation with a spine#

Every task gets an explicit contract first: what to build, how it ships, how much autonomy the worker has.
Workers are "supervised, not trusted." Independent validation and the configured merge authority sit between a worker's confidence and anything that lands.
"Unlanded work is never torn down; a refusal to discard is a finding, not an obstacle."

6. The fleet outlives any vendor#

It works on any verified harness (Claude Code, Codex, Pi, Grok, OpenCode, Cursor, omp) and any session manager (tmux, Herdr, Zellij, Orca, cmux).
Quota, model and effort choices stay yours. The first mate "never downgrades the intelligence doing the work without the captain's standing, explicit permission."

Scope: the command layer, not the workshop#

firstmate deliberately owns nothing below the command layer:

Concern	Owned by
Validation (review, tests, docs, lint)	no-mistakes
CI	your forge (GitHub, GitLab, Gerrit)
Merge policy	you, or a `+yolo` grant
Worktree pooling	treehouse (or Orca)
Session lifecycle / terminals	tmux, Herdr, Zellij, Orca, cmux
GitHub, browser, backlog, quota access	the AXI tools

It also "empowers exactly one individual". Collaboration between humans belongs to other systems.

When you need it (and when you don't)#

don't use firstmate until you feel the pain of juggling between many sessions and it became super clear that you can't scale further without some help. — @kunchenguid, 2026-09-09

After adopting it, Kun reports running 10–20 parallel sessions, up from 3–5. See Kun's playbook.