next level nerdingTalk to one agent. Ship with a crew.
Talk to one agent. Ship with a crew.
Firstmate is an agent distro you clone — not a model, harness, skill, MCP, or app. Launch a supported harness inside the clone; that session is your first mate; you are the captain. Parallel work without tab-juggling.
Start with the quick start, then walk the operate map.
Nine signals
The whole idea in nine boxes. Each links to the part of this page that explains it.
- 01
Clone it, don't install it
Firstmate is a folder of instructions, skills and scripts that you clone from GitHub. Start Claude Code, Grok or Pi inside that folder, and that session is Firstmate.
How - 02
You talk to one agent
You are the captain and you only talk to Firstmate. It starts the other agents, called crewmates, watches them and brings you only the decisions a person has to make.
How - 03
Scout before you ship
A scout investigates and writes a report without changing any project code. A ship is a change you approved. Only your word turns a scout into a ship.
How - 04
A diagnosis is not permission
A report or a recommendation approves nothing by itself. Merging, throwing work away and anything destructive wait for the captain to say so.
How - 05
Each crewmate gets its own copy
Every task runs in its own worktree, a throwaway copy of the repo, in a terminal pane you can look into. Parallel tasks do not trip over each other.
How - 06
A watcher keeps an eye on the crew
A small background script wakes Firstmate only when something needs attention, so you are not watching tabs. /afk lets you step away and still hear about failures.
How - 07
Review on a page, not in chat
Lavish opens the agent's HTML plan, wireframe or cost board on your machine. You point, annotate and pick an option, and the feedback goes back to the agent.
How - 08
Each project picks how strict to be
A project ships through no-mistakes (the full set of checks, then a PR), direct-PR (faster) or local-only. +yolo lets a green, low-risk change merge on its own; −yolo always waits for you.
How - 09
A restart is a non-event
Everything Firstmate needs to remember is saved on disk. Close any session and the fleet picks up where it was.
How
Words on this page
Twelve terms, in plain words. Skip this if you already run several coding agents at once.
- Harness
- The program that runs an AI model as an agent in your terminal. Firstmate works first with Claude Code, Grok and Pi, and also with Codex, OpenCode, omp and Cursor Agent CLI.
- AGENTS.md
- The instruction file inside the Firstmate clone. Launch a harness in that folder, it reads this file, and the session becomes Firstmate.
- Fleet
- All the projects you register under the projects/ folder, plus the crewmates working on them. Firstmate keeps track of the whole fleet for you.
- Crewmate
- One autonomous agent doing one task. Firstmate starts and supervises crewmates; you talk to Firstmate, not to them.
- Worktree
- A separate, throwaway working copy of a repo. Each crewmate gets its own, so parallel tasks do not collide. Kun uses Treehouse to make them.
- Session backend
- The terminal tool that keeps each crewmate running in its own visible pane, such as tmux (the default) or Herdr. You can look in, but you do not have to.
- Watcher
- A small background script that wakes Firstmate only when something needs attention. It is how Firstmate supervises crew without you watching tabs.
- Lavish
- Kun's review tool. It opens an agent's HTML page (a plan, wireframe or cost board) on your machine so you can point, annotate and choose, then sends your feedback back to the agent.
- PR (pull request)
- A proposed change on GitHub that waits to be merged into the main code. In most project modes a crewmate opens the PR and you say when to merge.
- Gate / green
- The gate is the set of checks a change must pass before it lands, such as review, tests, lint and CI. Green means every check passed.
- Collision check
- A check before a second ship starts on the same repo, so two crewmates do not trip over each other's changes.
- Teardown
- Closing a finished crewmate and removing its worktree. State stays on disk, so nothing is lost.
Quick start
Then talk only to Firstmate. AGENTS.md takes over.
gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate
claude
# or: grok --trust
# or: piWhat Firstmate is — and isn’t
What it is
A portable directory of instructions, skills, tooling, policies, and state. Clone = install. No app binary. Firstmate routes, supervises, and escalates only real decisions.
What it isn’t
Not a model, harness, skill, MCP server, or CLI product. Firstmate is read-only on your projects except narrow guarded ops. Crewmates do the work.
From the VISION
One captain, one interface
Crew never addresses the captain. Outcomes language. Machinery stays below deck.
Scripts = mechanics · agents = judgment
Exact work lives in scripts. Understanding lives in agents. The two never mix.
Restart-proof
State on disk. Kill any session; the fleet reconciles.
Peace of mind
Batching and silence never hide a failure, a decision, or a risk.
After install — captain on the bridge, crew on the water
Nautical bridge / fleet. Not a hub-and-spoke. Not idea→ship. Not a factory conveyor. Lavish is a side dock that can interrupt any mid-loop beat. Click a boat. Arrow keys walk the spine. Jumps land in Selected (#beat-spot).
talk only ▸
LiaisonFirstmateroutes · supervises · escalatesKeys: ← → walk the operate spine.
Selected beat
What / when / how / next. Jumps land here (#beat-spot), not on hidden sources.
Beat 03
Talk only to Firstmate
- What
- Captain interface: requests, decisions, “merge it.” Never babysit crew tabs as the UI. Crewmates never address the captain. Voice is OK.
- When
- Every operate turn after launch. Escalate only decisions a human can make.
- How
- Outcomes language — “fix the flaky login test and add dark mode,” not pane babysitting.
- Numbered menus when a real decision is needed (delivery gate; describe vs scout vs standby).
- Voice OK (OpenSuperWhisper in the intro). Typing reserved for URLs, branches, paths.
- Next
- Fleet setup / bearings, then intake.
Captain slash skills
Claude and Grok use the slash form. Codex uses $ — $afk. /calm is a harness toggle (Pi / Claude Code early-access), not the built-in skills table. /lavish is the lavish-axi skill. Pick one to open it in Selected.
Project modes
Each project ships via no-mistakes, direct-PR, or local-only, with optional +yolo / −yolo.
Scout vs ship — evidence ≠ authorization
Scout can recommend. Only captain word promotes to ship, collision-checked. Neither path blurs into the other on its own.
Scout
Investigate · report · teardown
Standalone report.md or Lavish HTML. No project code. Diagnosis ≠ authorization.
Ship
Authorized change · gate · teardown
Mode per project. PR or local merge. Captain word unless scoped +yolo + green gate.
Lavish deep panel
Operate beat, not a second FakeNerd product. Cite github.com/kunchenguid/lavish-axi.
Install
npx skills add kunchenguid/lavish-axi --skill lavishThat is the entire setup. The skill teaches the agent to run npx -y lavish-axi. Then:
/lavish let's discuss our plan herePrinciples
AXI
CLI any capable agent can run. TOON output, long poll, contextual disclosure. The skill is a stub; agents learn by running npx -y lavish-axi.
Artifact stays the author’s
Saved HTML is the source of truth. Serving adds one script tag. Renders identically with Lavish absent.
Interaction beats prose
Point, annotate, draw, choose. A page that could have been a paragraph should have been a paragraph.
Nothing interrupts the human
Detection is passive. Only a deliberate human action becomes feedback. Checks fail open.
Local-first
Review on the machine. Hosted sharing through ht-ml.app is explicit and opt-in.
Video examples
Intro ~24:25
Visual spec
Interactive HTML at 127.0.0.1:4387. Annotate DOM. Direction radios. Captain types start building. Session ends. Return to agent.
Throughput ~18:26
Bearings harvest
fm-bearings-board.v1 — 10 NEED YOU cards, radios (Ship interim / Wait / Park / Reconcile), Queue answer, Send & End.
Throughput ~25:36 · ~41:10
3D bird / mountain choosers
Contact sheets and shader studies. Forward / Iterate / Drop. Promote scout → ship only after captain choose.
Fullstack ~00:30
Eddie’s Wallet cost reject
Backend cost matrix. Annotate Supabase $25–40/mo. Push ~$5 Hetzner VPS. Excalidraw: phone is client; Postgres is referee.
Fullstack ~00:38–00:47
UX wireframes then PRD
Markdown scout ≠ playable. Escalate to interactive HTML wireframes. Close the loop → PRD README.
Fullstack ~01:34
Architecture while coding
Vertical-slice verdict, 23-endpoint table, auth sequence, ERD — pipelined with an AuthKit bugfix so nobody idles.
Secondmates / Relay — optional scale
Secondary rail. Opt-in, named, disclosed. Not primary spine noise.
Secondmates
Own FM_HOME
Persistent mates, local or SSH. Never silently replace an unavailable remote with local.
Relay
X / Discord @firstmate
Reversible mention lifecycle. Durable promised replies. One local .env pairing token.
Hard operate rules
From Firstmate VISION. Peace of mind is the purpose of the interface.
- 01One captain, one interface — crew never addresses captain. Outcomes language. Machinery below deck.
- 02Authority is explicit and never inferred. Merge, discard, and anything destructive need captain word.
- 03Evidence ≠ authorization. A diagnosis, report, or recommendation authorizes nothing by itself.
- 04Firstmate is read-only on projects except narrow guarded and captain-approved ops. Crewmates do the work.
- 05Scripts own the mechanics; agents own the judgment. The two never mix.
- 06A restart is a non-event. State lives on disk. Obligations close by records, not recollection.
- 07Every task gets an explicit contract: ship vs scout, mode, autonomy. The machinery refuses to guess.
- 08Batching and silence never hide a failure, a decision, or a risk.
FakeNerd's take
Copy the rules before the crew
The eight hard rules work in any agent with no install: a diagnosis is not permission, merges wait for your word, state lives on disk. Try them with one agent before you run five.
Scout before ship is the best habit here
Have an agent investigate and write a report, with no code changed, before anything gets built. It's cheap, it works anywhere, and it's the step most people skip.
Built for people already juggling agents
It assumes the GitHub CLI, worktrees, tmux panes and several repos at once. If you run one agent on one project, this is more machinery than you need yet.
Some skills are only in the README
/afk, /quiet, /stow and /updatefirstmate are described in the README, not shown in the three videos. /calm on Claude Code sits behind an early-access flag. Treat them as promises until you've run them.
His own tools, all the way down
Lavish and Treehouse are Kun's repos too, and the demos lean on them. The captain-and-crew idea doesn't need either, and in his own full-stack build he ran the lighter direct-PR mode, not the full gate.
Related on this site: Pi, one of the harnesses Firstmate runs on first. Rauch's workflow, the opposite bet: one small agent, one person. The software factory, the bigger picture of many agents working in a loop.
Attribution
- github.com/kunchenguid/firstmate
- github.com/kunchenguid/lavish-axi
- YouTube intro — L8 Principal's Agentic Engineering Workflow ·
iQyg-KypKAA - YouTube — High Throughput Agentic Engineering with Kun ·
MSbacZ99E14 - YouTube — L8 Principal Building a Full Stack App ·
kPN564Kol14 - X @kunchenguid · Discord · treehouse (worktree tool)
Footnote tools — fleet tools Firstmate coordinates / videos demonstrate, not Firstmate products: treehouse · Herdr / tmux / Orca backends · no-mistakes · gnhf · Atomic Vault.