p:: AI, Claude Code f:: herdr, tmux, worktrunk
An agent distro: a cloned repo made of AGENTS.md, bundled skills and helper scripts that turns a terminal coding agent into a supervisor. You talk to one agent (the first mate). It spawns autonomous crewmates, each in its own window in a session backend and its own git worktree. It supervises them to completion and hands back PRs, approved local merges, or investigation reports. You are the captain. There is nothing to install: launching a harness inside the checkout is the whole setup. MIT, macOS and Linux.
Install and launch
Needs Git and gh, authenticated.
git clone https://github.com/kunchenguid/firstmate
cd firstmate
claudeAGENTS.md takes over from there. It checks the toolchain and asks before installing anything that’s missing.
How it works
captain ──chat──▶ first mate (this repo, read-only over projects/)
│ spawns + watches
▼
fm-task1 … fm-taskN one agent each, own worktree
│
├─ ship: project mode ▶ PR / local merge ▶ teardown
└─ scout: data/<id>/report.md ▶ findings ▶ teardown- Backend: tmux by default. herdr is also supported, and Zellij, cmux and Orca are experimental. Each crewmate is a window or tab you can watch or type into.
- Worktrees: each task gets a clean treehouse worktree, so parallel tasks on one repo never collide.
- Supervision: a bash watcher sleeps on the fleet and only wakes the first mate when something needs attention. It spends no tokens while idle.
- Restart-proof: all state is on disk and in the backend. The next session reconciles.
Project modes
Set per project:
| Mode | Ships via |
|---|---|
no-mistakes | the no-mistakes gate: review, tests, lint, push, PR, CI |
direct-PR | the crewmate opens a PR itself |
local-only | an approved local merge, never pushed |
Optional flags: +yolo (lets the first mate merge on its own), branch=<prefix> (replaces the default fm/), and forge=gerrit (publish a Gerrit change instead of a PR).
Built-in skills
| Skill | Does |
|---|---|
/ahoy | recap what happened since your last message, then walk through open decisions one at a time |
/bearings | four-section fleet digest. file writes data/status-report-<date>.md, include PRs adds live GitHub data |
/afk | away-mode supervision while you step away |
/quiet | same token-saving supervision while you stay. Only /quiet off exits it |
/stow | save durable knowledge from the session and curate startup memory before a reset |
/updatefirstmate | guarded self-update and restart of every live mate |
In Codex the names take $ instead of /, e.g. $afk.