---
status: resolved
parent: "[[002-pi-subagents-map]]"
blocked-by: []
tags:
  - ticket/research
---

# Firstmate and related tools research

## Question

What do Kun Chen's Firstmate and related tools provide for spawning or coordinating coding agents, and can their approach be adopted or adapted for neutral Pi subagents that Herdr can observe?

## Resolution

## Findings

Firstmate describes itself as an agent distro rather than a model, harness, skill, MCP server, or CLI.
It is a portable directory of instructions, skills, tooling, policies, and state conventions that turns a supported terminal coding agent into a first mate that supervises a crew.
Citation: `/tmp/firstmate-research/firstmate/README.md` cloned from `github.com/kunchenguid/firstmate`.

Firstmate supports Pi as a primary harness alongside Claude Code and Grok, with Codex and OpenCode also verified.
Its quick-start says to launch `pi` inside the cloned firstmate repo and approve Pi project trust so tracked `.pi/extensions/*.ts` files auto-load.
Citation: `/tmp/firstmate-research/firstmate/README.md`.

Firstmate's model is intentionally much broader than a neutral subagent primitive.
It includes captain/crew roles, project modes, worktree management, PR delivery, supervision, secondmates, optional X-mode, state directories, and strict workflow policies.
Citation: `/tmp/firstmate-research/firstmate/README.md` and `AGENTS.md`.

Firstmate has a Herdr backend that can make every crewmate visible in Herdr.
The README says every crewmate works in its own tmux window, experimental Herdr or Zellij tab, cmux workspace, or Orca terminal.
The `fm-spawn.sh` header says a Herdr crewmate or scout is placed in the workspace of the launching firstmate or secondmate process, and `bin/backends/herdr.sh` says the authoritative target string is `<herdr-session>:<pane-id>`.
Citation: `/tmp/firstmate-research/firstmate/README.md`, `/tmp/firstmate-research/firstmate/bin/fm-spawn.sh`, and `/tmp/firstmate-research/firstmate/bin/backends/herdr.sh`.

Firstmate treats Herdr as a session provider only.
The Herdr backend header states that the worktree provider stays Treehouse, just like tmux, and Herdr owns the visible session endpoint shape.
Citation: `/tmp/firstmate-research/firstmate/bin/backends/herdr.sh`.

Firstmate's Herdr implementation is careful about identity and recovery.
It does not trust labels alone, records exact pane targets, uses home/session/workspace/tab/pane bindings, and treats presentation workspaces as non-authoritative visual projections.
Citation: `/tmp/firstmate-research/firstmate/bin/backends/herdr.sh` header and `/tmp/firstmate-research/firstmate/bin/fm-spawn.sh` header.

A secondary setup repository, `harish-nair-ai/agentic-workflow-setup`, confirms that Firstmate is one of Kun Chen's open-source tools and positions it among `lavish-axi`, `no-mistakes`, `gnhf`, and `treehouse` for agent-heavy workflows.
That repository is a checklist and source-grounded notes package, not the tool implementation.
Citation: `/tmp/firstmate-research/agentic-workflow-setup/README.md`.

A `shipmates` repository exists as a Hermes plugin for a Herdr/OpenCode/Firstmate-style experience, but its README is a short setup note and the cloned content does not establish a Pi subagent primitive.
Citation: `/tmp/firstmate-research/shipmates/README.md` and `plugin-guide.md`.

## Implications

Firstmate should not be adopted as the Pi subagent extension.
It is intentionally an opinionated operational distro with roles, policies, project lifecycle, and worktree/PR machinery, which conflicts with the desired boundary that the extension provides mechanism and Pi configuration provides subagent types.

Firstmate is highly relevant as a design reference for Herdr compatibility.
Its Herdr backend demonstrates that Herdr-visible agent spawning is feasible and that robust integration should treat pane identity as authoritative rather than relying on labels or loose process discovery.

Treehouse and related tools may be useful if the future destination includes isolated worktrees or PR-oriented crew workflows, but those are outside this decision map's neutral subagent capability.

## Limitations

This research inspected Firstmate source headers and README-level architecture rather than running Firstmate.
Running it would mutate local state and is unnecessary for the current adopt/adapt/build decision.
