Overview

Firstmate is a revolutionary agent distribution system that transforms how you manage AI-powered coding tasks. Forget juggling multiple agent sessions and context. Firstmate lets you interact with a single "first mate" agent, which then orchestrates a "crew" of autonomous agents in the background. Each crewmate operates in an isolated environment, ensuring parallel tasks like bug fixes, investigations, and code audits never collide. This system is designed to be a portable directory of instructions, skills, and tooling, turning any compatible terminal coding agent into a specialized, multi-agent command center.

Key Features

• Single Point of Contact: Interact solely with the first mate. It handles dispatching, supervision, escalation, and consolidation of results.
• Visible Crew Sessions: Monitor and interact with individual crewmates in dedicated tmux windows or other supported terminal multiplexers, with the first mate reconciling their outputs.
• Isolated Worktrees: Each task utilizes a clean, disposable treehouse or Orca-managed git worktree, guaranteeing no interference between parallel operations.
• Dual Task Modes: Ship tasks for direct code changes (via PRs, local merges, or no-mistakes modes) or deploy scout tasks for in-depth investigations that yield standalone reports.
• Persistent Secondmates: Extend your crew with optional, persistent secondmate agents that can run locally or on remote SSH-accessible hosts, maintaining their own state and projects for resilient, distributed operations.
• Restart-Proof State Management: All state is durably stored on disk and in the active session backend, allowing you to kill and restart sessions without losing progress or confirmed work.
• Event-Driven Supervision: A zero-token, bash-powered watcher intelligently wakes the first mate only when attention is required, minimizing unnecessary overhead.
• Optional Social Relay: Integrate with X and Discord to allow your first mate to respond to public mentions, acknowledge work, and post progress updates, all while maintaining privacy and control over communications.
• Strict Project Boundaries: The first mate operates with read-only access to your projects, with all modifications strictly guarded and captain-approved, ensuring operational integrity.

Typical Use Cases

• Parallel Development & Debugging: Effortlessly run multiple bug fixes, feature implementations, or performance analyses concurrently without manual context switching.
• Automated Code Audits & Investigations: Deploy scout agents to thoroughly investigate codebases, identify vulnerabilities, or generate detailed reports without cluttering your primary workflow.
• Streamlined CI/CD Integration: Integrate firstmate into your development pipeline to automatically handle code reviews, generate PRs, and manage local merges based on predefined project modes.
• Managing Complex Projects: For larger codebases or intricate tasks, leverage secondmates to distribute workload across local machines or even remote servers, enhancing scalability and resilience.
• Collaborative AI Development: Experiment with and manage multiple AI agents working together on a common goal, overseen by a single, intuitive interface.
• Enhanced Agent Interaction: If you're using an AI coding assistant, firstmate elevates its capabilities from a single-task performer to a fleet manager, significantly boosting productivity.