DOCSEARCHbyAlgolia
Submit Docs

firstmate Agent Distro

repository·main·Indexed 20 days ago

https://github.com/kunchenguid/firstmate

An agent distro that allows users to manage a crew of autonomous coding agents through a single liaison (the first mate). It features worktree isolation via treehouse or Orca, visible session backends like tmux, and event-driven supervision. firstmate supports primary agent harnesses including Claude Code, Grok, Pi, Codex, and OpenCode, providing specialized task types such as 'ship' for PRs and 'scout' for investigation reports.

Tokens
54.7K
Snippets
60
Records
260
Agent score
78%

What's inside firstmate

  1. Use the Watcher arm PreToolUse seatbelt

    main

    The Watcher arm PreToolUse seatbelt is a security mechanism designed to prevent agents from executing shell commands that could bypass supervision (e.g., using background operators, pipelines, or redirections to hide a watcher command).

    It works by tokenizing the command and classifying lexical execution positions. It does not execute, source, or expand the command. It is a static analysis tool used to reject unsafe command shapes before they are run.

    Key Protections:

    • Rejects commands that attempt to run bin/fm-watch.sh directly (use bin/fm-watch-arm.sh or bin/fm-watch-checkpoint.sh instead).
    • Rejects commands that attempt to hide watcher execution via pipelines, redirections, or backgrounding.
    • Rejects commands that attempt to kill the watcher process (e.g., pkill -f fm-watch).
    • Rejects complex or unsupported shell grammar that might contain a hidden watcher command.

  2. What is firstmate?

    main

    firstmate is an agent distro designed to run a crew of autonomous agents. Instead of managing multiple terminal sessions and context-switching manually, you interact with a single liaison called the first mate.

    Key characteristics:

    • Liaison Model: You talk to the first mate; it dispatches, supervises, and reports outcomes from the crew.
    • Visible Crew: Crewmates work in isolated, visible sessions (e.g., tmux windows, zellij tabs) that you can monitor.
    • Worktree Isolation: Each task runs in a clean treehouse git worktree or an Orca-managed worktree to prevent collisions.
    • Task Types: Supports ship tasks (delivering PRs or local merges) and scout tasks (delivering standalone investigation reports).
    • Restart-proof: All state is stored on disk and in the active session backend, allowing you to resume work after a restart.

  3. Pi compatibility and extension resilience

    main

    Calm mode is designed to be resilient to Pi version changes. It does not have a specific numeric version requirement and will not refuse to run simply because Pi is newer than a previously verified version.

    Resilience Mechanism: Calm uses presentation adapters that probe specific Pi API seams. If Pi removes a seam that an adapter relies on:

    1. Calm logs a diagnostic naming the unavailable adapter.
    2. Calm skips only that specific adapter.
    3. The /calm command and all other unrelated Pi extensions remain functional.

  4. Understand Herdr environment variable injection

    main

    Firstmate relies on Herdr to inject specific identity variables into managed processes. For a process to be recognized as having 'launcher ancestry', both HERDR_PANE_ID and HERDR_SOCKET_PATH must be present in its environment.

    # Example injected environment variables
HERDR_ENV=1
HERDR_PANE_ID=w1:p1
HERDR_SESSION=fm-lab-fm-herdr-env-pro-65961-25535
HERDR_SOCKET_PATH=/Users/kunchen/.config/herdr/sessions/fm-lab-fm-herdr-env-pro-65961-25535/herdr.sock
HERDR_TAB_ID=w1:t1
HERDR_WORKSPACE_ID=w1

  5. Manage Captain Preferences

    main

    Captain preferences define domain-local settings for a fleet. These are stored in two types of files:

    1. Domain-local preferences: Stored in data/captain.md within each home. This file is gitignored and included in the session-start context digest. To modify, inspect the file and rewrite or prune matching bullets in place. Add new bullets only for durable preferences.
    2. Shared captain preferences: Stored in the primary home's data/captain-shared.md. These apply across all secondmate domains.

    Note: secondmate-provisioning manages the propagation of shared preferences. Existing homes are expected to trim their local data/captain.md manually after the first propagation to avoid accidental deletion of private content.

  6. How OpenCode TUI plugin supervision works

    main

    Supervision in OpenCode TUI sessions is managed by a persistent plugin runtime that ensures continuity of the 'arm' mechanism.

    Mechanism Details:

    • Idle Trigger: The plugin listens for session.idle events.
    • Process Spawning: Upon idling, it spawns bin/fm-watch-arm.sh --restart. This is spawned without awaiting it in the idle handler, allowing the plugin to own all subsequent successor launches.
    • Successor Management: After an actionable child process closes, the plugin verifies session-lock ownership and ensures exactly one singleton successor exists before calling client.session.promptAsync.
    • Error Handling: If a child process closes unexpectedly, the plugin enters a bounded exponential retry. If retries are exhausted or the session lock is lost, it surfaces a 'watcher failure' rather than silently failing.
    • Scope: The plugin applies to the main primary checkout and a secondmate's home, but remains silent in child crewmate and scout worktrees.

  7. Requirements for GitLab merge request watching

    main

    To use the GitLab merge request watcher, the following requirements must be met:

    1. glab CLI: Must be installed and available in your PATH. If glab is missing, fm-pr-check.sh will return an error code 1 and refuse to arm the watch.
    2. URL Access: The watcher uses glab mr view <number> -R <project_url> to resolve the instance and view the merge request state. This allows it to work without being inside a local git repository.
    3. State Detection: The watcher looks for the exact string merged in the state: field of the glab output. If the output format changes or glab is unavailable, the poll remains silent rather than triggering a false merge.

  8. How presentation spaces and journals work

    main

    Presentation is a best-effort visual projection, not a mechanism for task ownership or lifecycle authority. It uses a two-stage journaling system to manage workspace creation:

    1. Version 1 Journal: Firstmate atomically publishes a three-field journal containing a random 128-bit base64url token before requesting Herdr to create a workspace. This token is visible in the workspace title.
    2. Version 2 Binding: Once the workspace converges to an exact task endpoint under a parent workspace ID, the journal advances to version 2. This records the physical home, named session, endpoint, parent, and immutable expected labels.

    Key Constraints:

    • Only a fresh task with no existing metadata or presentation journal is eligible for projection.
    • A parent with the same presentation label does not prevent publication or participate in restart reclaim.
    • The token, title, or journal does not authorize task ownership, Treehouse return, or general recovery; they are primarily for visual correlation and restart stability.

  9. Understand Project Delivery Modes

    main

    Project behavior is defined in data/projects.md through specific delivery modes and an optional +yolo autonomy flag. These modes determine how code is validated and merged.

    Supported Modes:

    • no-mistakes: Runs the full validation pipeline. For target repos, validation evidence is stored in .no-mistakes/evidence/.
    • direct-PR: Opens Pull Requests without running the validation pipeline.
    • local-only: Keeps changes local until an approved fast-forward merge is performed.

    Merging and Reviewing:

    • Diffing: bin/fm-review-diff.sh refreshes the authoritative base. If task meta records pr=, it fetches and compares against refs/pull/<n>/head by default.
    • PR Merging: bin/fm-pr-merge.sh handles merges via gh-axi pr merge <n> --repo <owner>/<repo>. It defaults to --squash and requires a full GitHub Pull Request URL. It explicitly rejects GitLab URLs.
    • Teardown: Teardown is "fail-closed" for ship worktrees. Dirty worktrees are refused, and all committed work must be landed before the worktree can be returned.

  10. Understand documentation audience classifications

    main

    Firstmate uses specific audience classes to determine where information is placed. When contributing or reviewing documentation, ensure content is assigned to the correct class:

    • public-product: Standalone public material or product introductions.
    • operator-current: Explanations of current behavior, setup, supported limits, stable invariants, rationale, and verification entry points.
    • operator-example: Copyable, current setup material.
    • maintainer-architecture: Explanations of stable ownership, extension points, mechanism boundaries, and safety rationale for contributors.
    • maintainer-verification: Repeatable evidence for active guarantees (includes dates, versions, exact commands, and output).
    • agent-runtime: Operating contracts specifically for Firstmate agents (rendered/loaded rather than read as product docs).

  11. Orca backend limitations and safety

    main

    When using the Orca backend, be aware of the following constraints:

    • Platform: macOS only.
    • Spawns: secondmate spawns are unsupported.
    • Input: The Escape key is unsupported.
    • Detection: Must be explicitly configured; it is never auto-detected.
    • Stability: Orca does not provide a stable CLI version or protocol marker. Readiness is determined by the response of orca status --json rather than a version check.
    • Data Integrity: Firstmate uses verified terminal.handle and worktree result fields. Speculative response shapes are rejected to ensure safety.
    • Cleanup: Firstmate never performs a raw delete of an Orca worktree. It resolves the recorded orca_worktree_id and verifies the path matches the recorded worktree path before using Orca's specific worktree command to release it.

  12. Understand the Two-tier skill layout

    main

    Firstmate distinguishes between skills meant for the agent and skills meant for standalone project use. This separation ensures that internal automation does not interfere with public tool availability.

    1. Agent-loaded skills (.agents/skills/)

    These are internal skills used by Firstmate's automation. They are marked with metadata.internal: true in their frontmatter. This flag prevents them from being discovered by external installers (like npx skills add) while still allowing Firstmate to load them.

    2. Public skills (skills/)

    These are standalone skills intended to be installed into any project independently of Firstmate. They have no dependencies on Firstmate's internal paths, tools, or vocabulary.

    Example: The skills/stow skill is a generic version of the internal /stow skill. It routes findings via explicit instructions, local conventions, or a .stow-notes.md fallback, allowing it to evolve independently from the Firstmate-internal version.