Chapter 1 · FirstMate Overview: Agent Distro and Fleet Philosophy

Chapter goals: Understand the core pain point FirstMate solves, its unique positioning as an agent distro, and the four-layer captain/firstmate/crewmate/secondmate role system with the overall architecture.

1.1 The Single-Agent Dilemma: The tab-juggler Problem

Running a single coding agent is easy: open a terminal, start Claude Code or Pi, give it a task, wait for the result.

But when you want to advance three project tasks simultaneously — fix a bug, do a code audit, write a technical proposal — the situation changes. The official README describes this precisely:

you become a tab-juggler: babysitting sessions, copy-pasting context
between repos, forgetting which terminal had the failing test.

This is the tab-juggler problem:

• Each agent session requires manual babysitting;
• Context between tasks is搬运 by hand-copy-paste;
• With multiple terminal windows running in parallel, it's quickly unclear which session is doing what.

The traditional fix is to open an agent window per task — but this just swaps the "managing code" problem for a "managing agents" problem.

1.2 FirstMate's Flip: Talk to one agent. Ship with a crew.

FirstMate's slogan captures its model flip in one line: Talk to one agent. Ship with a crew.

You no longer direct multiple agents one by one; instead, you converse with only one fixed agent — firstmate — and it调度 the entire crew on your behalf:

You (captain)
    │ Talk only to firstmate: make requests, make decisions, "merge it"
    ▼
firstmate (this repo is the distro)
    │ Read projects/ and route requests; write to guarded backlog/briefs/state
    ├──────────────┬──────────────┐
    ▼              ▼              ▼
fm-task1        fm-task2   ...  fm-taskN     ← each runs an autonomous agent
(crewmate)      (crewmate)      (crewmate)      in its own tmux window or equivalent backend
    └──────────────┴──────────────┘
                    ▼
        treehouse git worktree (one clean worktree per task)
            ├─ ship tasks: project mode ► PR/local merge ► teardown
            └─ scout tasks: data/<id>/report.md investigation report ► teardown

Throughout the entire flow:

1. You make requests to firstmate in natural language;
2. firstmate routes each request to a crewmate; each crewmate works in its own session backend (tmux window etc.) and an independent git worktree;
3. firstmate supervises the entire fleet with a zero-token event-driven watcher, waking only when you need to intervene;
4. What lands on your desk is completed PRs, approved local merges, or independent investigation reports.

The official real conversation experience looks like this:

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

# firstmate checks the toolchain (asks your consent before installing anything),
# clones the project under projects/ and spins up two isolated workers in the current backend.
# A few minutes later:

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

> alright merge it

Two details to note: firstmate addresses you as captain; it only executes the merge after you say alright merge it — merge authority始终 stays with you.

1.3 What FirstMate Is: An Agent Distro

The FirstMate official docs position itself with a series of "not"s:

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.

It is not a model, not a harness, not a single skill, not an MCP server, not a CLI. It is an agent distro:

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.

This means There is no app to install: the cloned repo is the distro — there is no application to install; the cloned repository itself is the distro. Three categories of things in the repo构成 firstmate's entire capability:

firstmate/
├── AGENTS.md          # Operations contract: always-loaded job description and routing index
├── .agents/skills/    # firstmate internal skills (agent-loaded, metadata.internal=true)
├── skills/            # Public-installable standalone skills
├── bin/               # fm-* auxiliary script toolbelt (supervision, dispatch, status, control...)
├── docs/              # Architecture, config, per-backend setup guides
└── tests/             # Test suite

Any terminal coding agent that can read AGENTS.md and is launched inside this repo directory becomes instantiated as your firstmate.

1.4 Four-Layer Role System

FirstMate uses a nautical metaphor to建立 a strict chain of command:

Role	Nautical Identity	Responsibility
captain	Captain (you)	The sole decider: make requests, approve merges, make all real decisions
firstmate	First Mate	The sole liaison: receives all captain instructions, dispatches, supervises, escalates, reports
crewmate	Crew	Autonomous agents pulled up by firstmate, working on concrete tasks in独立 worktrees
secondmate	Second Mate (optional)	A "persistent crew member" running from its own isolated FM_HOME;本质上仍是直接下属

Key relationships:

• One-way communication: all crewmate通信 must go through firstmate; crewmates never report directly to captain (this is Hard Rule 4, covered in Chapter 4);
• secondmate is not a second architecture: the official docs emphasize "A secondmate is a crewmate with an isolated firstmate home and a charter, not a second architecture" — it's a crewmate with an isolated home dir and charter, not another mini-firstmate command chain;
• Scale elasticity: one crewmate is enough when scale doesn't demand more;启用 secondmate only when the fleet grows or跨 machine operation is needed.

1.5 Ten Core Capabilities

The feature list from the official README, worth knowing one by one (each will be展开 in subsequent chapters):

1. One liaison — talk only to firstmate: it dispatches, supervises to completion, escalates only real decisions, reports in plain results;
2. A visible crew — each crewmate works in its own tmux window (or herdr/zellij tab, cmux workspace, Orca terminal); you can观 and even插话 directly; firstmate mediates;
3. Disposable worktrees — each task runs in a clean treehouse git worktree; parallel work on the same repo doesn't conflict;
4. Two task shapes — ship tasks deliver authorized changes; scout tasks produce independent investigation reports;
5. Explicit project modes — each project delivers in no-mistakes, direct-PR, or local-only mode; optional +yolo merge autonomy flag;
6. Optional secondmates — persistent second mates running from isolated firstmate homes; supports local or SSH-reachable remote hosts;
7. Event-driven, zero-token supervision — bash watcher sleeps monitoring the fleet, wakes firstmate only when you need to intervene; verified main harness also has turn-end fallback to prevent "blind stops";
8. Optional Relay — enabled with a local .env paired token, letting the same fleet respond to your public mentions on X and Discord;
9. Strict project boundary — firstmate is read-only to your projects by default; all project changes are completed by crewmates behind configured merge permissions;
10. Restart-proof — all state lives on disk and in the active session backend; kill sessions anytime; the next session reconciles and continues.

These ten points group into three: how to work (2/3/4), how to delegate (5/6/9), how to sleep easy (7/8/10). Point 1 is the交互 principle贯穿 everything.

1.6 How FirstMate Differs from Other Multi-Agent Solutions

Placing FirstMate in the framework coordinate system you've already learned makes its unique position clear:

• Agno / CrewAI / Mastra / Flue are code frameworks for writing multi-agent applications — you write Python/TypeScript to define Agents and orchestration logic;
• Claude Code / Pi are single-agent runtime frameworks — one session at a time;
• FirstMate writes zero application code; instead, it uses an AGENTS.md contract plus a shell toolbelt to organize your existing coding agent CLI into a disciplined fleet.

In other words, the frameworks you learned earlier solve "how to造 agents"; FirstMate solves "how to command a group of existing agents." All its logic happens at the OS level: git worktrees, tmux sessions, disk state files, bash watchers — which is why its implementation language is almost entirely Shell.

1.7 Chapter Summary

• FirstMate solves the tab-juggler problem: the manual babysitting burden of multiple parallel agent tasks;
• Core model flip: you are captain, talking only to firstmate as the single liaison; it指挥 the crewmate fleet to deliver PRs or investigation reports;
• FirstMate is an agent distro — a portable directory of instructions, skills, tools, policies, and state conventions; cloning the repo completes "installation";
• Four-layer role system: captain (decide) / firstmate (liaise & supervise) / crewmate (execute) / secondmate (persistent isolated execute); communication strictly one-way;
• Ten capabilities cover task shapes (ship/scout), safety boundaries (project modes, hard rules), and peace-of-mind mechanisms (zero-token supervision, restart-proof, Relay).

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. How does FirstMate officially position itself?

2. Regarding the relationship between captain and firstmate, which is correct?

3. After a crewmate completes a ship task, what is the usual final deliverable?

4. Why is FirstMate described as restart-proof?

🛠️ Hands-On Exercises

1. Open the FirstMate repo at https://github.com/kunchenguid/firstmate; read the What it is and How It Works sections of the README; explain "agent distro" vs traditional multi-agent frameworks to a colleague in your own words (under 200 words).
2. Draw a variant of the architecture diagram in Section 1.2: assume the fleet has 1 secondmate and 3 crewmates; annotate who initiates each communication line, who it passes through, and who the endpoint is; check whether any line bypasses firstmate. 3.对照 the ten-capability checklist, pick the three you think are most important for "solo developer independent work"; write reasons. Then pick three most important for "team collaboration scenarios"; compare the two groups' differences.

The conceptual map is complete. Next, set up the environment and take first sail.