Chapter 2 · Environment Setup and First Sail

Chapter goals: Prepare the full toolchain needed to run FirstMate from scratch, complete cloning and first startup, and run through the minimal closed loop of "issue request → crew works → PR returned."

2.1 Platform and Prerequisites

FirstMate is a pure Shell-organized agent distro. Officially supported platforms:

macOS / Linux (native Windows not supported; can try in WSL2 but no official guarantee)

Three categories of tools are required before starting — none can be omitted:

Category	Tool	Purpose
Auth	GitHub CLI (gh)	Clone repos, create PRs, read CI status
Version control	git	Project cloning, worktree isolation
Session backend	tmux	Reference backend, hosts each crewmate's visible session
Primary harness	Claude Code / Grok / Pi etc.	Runs the firstmate's own agent runtime

tmux is the reference backend (reference backend): all supervision behaviors in the docs are verified against it; herdr, zellij, Orca, cmux are experimental backends (covered in Chapter 7). Beginners should start with tmux.

2.2 Choosing the Primary Harness

The primary harness is the terminal coding agent that hosts the firstmate session. FirstMate officially validates:

Claude Code   grok   pi   pi-signed   Codex   OpenCode   Cursor Agent CLI

Among these, Claude Code, Grok, and Pi are three equal co-primary recommendations — pick whichever you have a subscription for; the difference is only in the supervision接入 mechanism:

Harness	Supervision接入 Method
Claude Code	tracked Stop hook; re-arms the watcher tokenlessly and wakes on need
Grok	background-notify wake loop
Pi	tracked primary watcher extension

All three have verified turn-end guard paths (covered in detail in Chapter 11). Codex and OpenCode are also supported but rely on bounded foreground checkpoints and TUI plugins respectively, with more supervision trade-offs. Cursor Agent CLI uses project-level .cursor/hooks.json stop hooks; structurally closest to Claude Code.

Selection advice: follow your subscription — whatever provider you already subscribe to is the one to use; FirstMate treats all three equally.

2.3 Installing and Cloning

Complete GitHub CLI authentication first, then clone the distro:

# 1. Login to GitHub (follow the browser auth flow)
gh auth login

# 2. Confirm auth status
gh auth status

# 3. Clone the firstmate distro and enter the directory
git clone https://github.com/kunchenguid/firstmate
cd firstmate

No app to install, no global command to register — the cloned repo itself is the distro: AGENTS.md is the operations contract, .agents/skills/ are built-in skills, bin/ is the script toolbelt.

2.4 First Launch

Inside the firstmate directory, launch your chosen harness directly — AGENTS.md自动 takes over as the firstmate's job description:

# Claude Code
claude

# Grok (--trust once per cloned repo; lets project hooks and turn-end guard load)
grok --trust

# Pi (approve the project trust prompt once on first launch; .pi/extensions/*.ts auto-load)
pi
# Or use the signed wrapper
FM_PI_HARNESS=pi-signed pi-signed

Pi also provides a /calm switch: hides some transcription UI noise (including Firstmate operation rows classified as规范) and replaces normal output with a Calm animation sailboat during active runs, without changing any model context or session data; run /calm again to restore normal rendering.

2.5 What Happens at Startup: Session Startup Summary

Each session start, the firstmate runs bin/fm-session-start.sh, producing a startup digest in fixed order:

1. Lock              Acquire the session lock for this home; if locked, run read-only for the whole session
2. Bootstrap         Read-only probe for tools/version issues; installs require your on-the-spot consent
3. Wake queue        Present the persistent wake queue (leftover work notifications from last session)
4. Supervision       Output the supervision操作指令 block matching your current harness
5. Fleet-state       Quick inventory of each task's alive status (only checks "is it there", doesn't deep-read)
6. Network checks    Concurrent results of GitHub auth, secondmate alive checks, etc.
7. Context digest    Full text of projects/secondmates/captain/learnings archives

Two rules most important for newcomers:

• Bootstrap detects but does not install: when missing tools are found, a清单 is presented asking your consent; it installs only after you say yes;
• Lock denied = read-only: if another active session holds the lock, this session will not spawn, merge,或 modify any fleet state — it only reports diagnostic info.

ABSENT markers in the digest are normal — e.g., data/captain.md not existing means "use built-in default preferences," not an error.

2.6 First Conversation: Running the Minimal Closed Loop

After startup completes, issue a task in natural language. Official example:

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

This message contains two tasks; the firstmate auto-decomposes and routes them:

Task 1 (ship): fix flaky login test      → Crew A works in an独立 worktree
Task 2 (ship): add dark mode             → Crew B works in another独立 worktree

A few minutes later you receive a report like:

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

> alright merge it

Three要点 in this conversation to note:

1. You talk only to the firstmate; never direct any crewmate directly;
2. Merge requires your explicit nod — "alright merge it" is the captain's explicit word (Hard Rule 2, Chapter 4);
3. The report leads with results (PR ready, risk low, CI green), not intermediate process details.

2.7 Common Troubleshooting

Symptom	Cause and Fix
No hooks loaded after startup	Grok forgot --trust; or execute /hooks-trust inside the session to补授权
Pi didn't load the watcher extension	The first trust prompt was rejected; re-approve project trust
Prompt says tmux is not installed	brew install tmux (macOS) or apt install tmux (Debian/Ubuntu)
Prompt says GitHub auth failed	Re-run gh auth login; confirm gh auth status passes
Session startup digest shows lock denied	Another session is already managing the fleet; close the old session or wait for it to release the lock

2.8 Chapter Summary

• FirstMate supports macOS/Linux; depends on gh + git + tmux reference backend + one validated primary harness;
• Claude Code / Grok / Pi are three equal co-primaries; difference is only in supervision接入 mechanism;
• Clone = install: the repo itself is the agent distro, no extra app needed;
• Session startup digest follows fixed order: Lock → Bootstrap → Wake queue → Supervision → Fleet-state → Network checks → Context digest;
• Bootstrap detects first, installs only after captain consent; minimal closed loop = natural language request → dual worktree parallel → PR returned → captain verbal authorization to merge.

🧪 随堂测验

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

1. Which is FirstMate's official reference session backend?

2. Regarding the three co-primary harnesses (Claude Code, Grok, Pi), which statement is correct?

3. What is Bootstrap's install strategy in the session startup digest?

4. In the first conversation "fix the flaky login test and add dark mode", how does the firstmate handle these two changes?

🛠️ Hands-On Exercises

1. Walk through steps 2.3–2.4 completely on your machine: authenticate gh, clone firstmate, launch a co-primary harness you have a subscription for, and抄录 all seven digest blocks to对照 this chapter.
2. Intentionally launch the firstmate in an environment without tmux installed (or temporarily rename the tmux binary); observe how Bootstrap reports the missing tool and its install suggestion流程;记录 the difference between "before consent" and "after consent."
3. Pick a practice repo of yours; issue a natural-language request with two changes using the dual-task pattern from Section 2.6; observe how the firstmate拆 tasks, how many tmux windows it opens, and whether the final report包含 all three elements: full PR URL, risk label, and CI status.

First sail complete. Next, dive into AGENTS.md anatomy — the firstmate's job description.