engineering / agent

firstmate

Instructions, skills and scripts for dispatching and supervising parallel coding agents in Git worktrees.

Repository owner kunchenguid

Not rated yet
0 comments

Like 0 Save

Published 11 Oct 2026Listing updated 12 Oct 2026

At a glance

Purpose: Instructions, skills and scripts for dispatching and supervising parallel coding agents in Git worktrees.
Runs in: Local agent with shell
Operating systems: macOS, Linux
Needs: Runtime: Git, GitHub CLI and tmux (default backend); Needs internet: Yes; Needs accounts or API keys beyond your agent: Yes
Files and data: Reads files: Yes; Writes files: Yes; Sends data to other services: Yes
Tool type: Agent
Delivery: From GitHub
Version: Latest on the main branch
Access: Code on GitHub
Compatibility: According to the README, firstmate runs on macOS and Linux. It lists the primary harnesses Claude Code, Grok, Pi, pi-signed, Oh My Pi (omp), Codex, OpenCode and Cursor Agent CLI. The README lists tmux as the reference default, Herdr, and experimental Zellij, cmux and Orca session backends. The README requires Git and the GitHub CLI. The README mentions an optional Gerrit binding for publishing changes instead of pull requests, and an optional Relay that answers mentions on X and Discord.
External costs: According to the README, firstmate runs inside a supported agent harness, and it says to pick the primary harness that matches your subscription and workflow. It also needs the GitHub CLI signed in with gh auth login. The repository is MIT-licensed and states no pricing. Your coding agent or model provider may charge for usage.
Permissions: The README says crewmates work in separate Git worktrees and can deliver pull requests or local merges under the configured merge authority; project modes have an optional +yolo merge-autonomy flag. The README says the first mate has a read-only project boundary with narrow guarded, captain-approved exceptions, including branch pruning during fleet sync. The README describes a background watcher, harness hooks and extensions, and away or quiet supervision through a host, branch or daemon; the quiet daemon remains active until /quiet off. The README says missing-tool installation requires approval. The README describes persistent state writes, self-updates and mate restarts, optional SSH-reachable secondmate homes, and an opt-in Relay using a local pairing token to act on mention requests and post public replies on X and Discord.
Usage terms: MIT License, as stated in the repository. See its LICENSE file for the exact terms.

Code on GitHub

kunchenguid/firstmate

MIT

Shell7,850 stars2,535 forksLast pushed 12 Oct 2026 UTC

Talk to one agent. Ship with a crew.

Public GitHub data fetched 13 Oct 2026 UTC · 0 days old

Skill folders in this repository (29)

Folders that contain a SKILL.md file, from GitHub's file list on 13 Oct 2026 UTC.

View on GitHub ↗

What it does

The README calls firstmate an agent distro: a directory of instructions, skills, tooling, policies and state conventions for a terminal coding agent. The README says you clone the repository and launch a supported harness inside it rather than install an app.

The README says the first mate dispatches and supervises autonomous crewmates in separate Git worktrees and visible sessions, and reports pull requests, approved local merges or investigation reports. The README names no-mistakes, direct-PR and local-only project modes.

The README lists the user-invocable skills afk, quiet, ahoy, bearings, updatefirstmate and stow. The README also describes agent-only reference skills, standalone public skills, optional secondmates with isolated homes locally or on an SSH-reachable host, and an opt-in Relay for public mentions on X and Discord.

Who it is for

Developers who already use a supported terminal coding agent and want one agent to dispatch and supervise parallel tasks across their projects.

Example tasks

Ask the first mate to fix a flaky test and add a feature in a GitHub project, then check the pull request it reports.
Ask the first mate for an investigation that ends in a standalone report.
Use the bearings skill to get a four-section digest of the fleet in chat.
Use the afk skill to enter away-mode supervision while you step away.
Install the standalone stow skill into another project.

Getting started

According to the README, run gh auth login, clone the repository, run cd firstmate, then start one of the supported harnesses in that folder from a terminal. The README shows claude for Claude Code, grok --trust for Grok, pi for Pi and omp for Oh My Pi. The README says AGENTS.md then takes over. The README says the first mate checks its toolchain and asks for consent before installing anything. You give it requests in chat. The README lists its built-in skills separately and says Claude and Grok use the slash form, such as /afk, while Codex uses the same names with a $ prefix. The README has the exact commands.

Limitations

The README shows macOS and Linux support and requires a primary harness: Claude Code, Grok, Pi, pi-signed, Oh My Pi (omp), Codex, OpenCode or Cursor Agent CLI. The README also requires Git, the GitHub CLI authenticated with gh auth login, and the CLI and dependencies for your chosen session backend. The README calls tmux the reference default and marks Zellij, cmux and Orca as experimental. The README says Cursor Agent CLI needs --trust and an interactive primary session because headless mode has no turn-end hook. The README says Codex and OpenCode have more supervision tradeoffs than Claude Code, Grok and Pi. The README says to start omp in the checkout and avoid also loading its automatically discovered extensions with -e, which would load them twice. The README warns that .agents/skills assumes a live firstmate home and can be meaningless or misleading elsewhere; skills/stow is the standalone public skill. The README says missing-tool installation requires your approval. The repository can change at any time; check its README before you install.

Data practices

According to the README, all firstmate state lives on disk and in the active session backend. What is sent where depends on the agent harness and model provider you run. The optional Relay is enabled with a local .env pairing token and answers public mentions on X and Discord. The README does not mention telemetry.