The hidden truth inside Firstmate AI
Summary
This video explores the AI agent landscape, focusing on the 'Firstmate' project and its underlying principles. The creator argues that instead of adopting others' tools, the highest productivity gain comes from building software that adapts to individual workflows. The video details Firstmate's architecture, its CLI wrappers, and presents four key principles for creating personalized AI agent systems: wrapping existing CLIs, building new ones when needed, verifying AI output through automated pipelines rather than babysitting, and creating reusable, systematic automations. It emphasizes that AI makes custom tooling accessible, but warns of maintenance costs and the importance of personalization over adopting pre-built stacks.
Key Insights
Firstmate's underlying infrastructure relies on numerous custom-built CLI tools, forming a personal 'agent stack'.
The bootstrap script for Firstmate checks for eleven tools, many created by Kun Chen, such as gh-axi (GitHub CLI wrapper), chrome-devtools-axi (browser automation wrapper), and no-mistakes (validation pipeline with 7.5k stars). This forms a comprehensive personal stack for agent experience (AXI).
Firstmate uses an event-driven system with a zero-token watcher, codifying reasoning into bash scripts.
Instead of traditional heartbeats common in asynchronous systems, Firstmate utilizes a deferred process managed by a script. This approach optimizes token usage by codifying the reasoning process into bash scripts, effectively using AI to automate AI agent thinking work.
Principle 1: Wrap existing CLIs to tailor them for agent use cases, reducing complexity and round trips.
Wrapping CLIs like GitHub's with tools such as gh-axi creates smaller, more focused outputs that are easier for agents to parse. This reduces the number of agent turns required, minimizes potential failure points, and saves tokens. Examples include pre-computing data and suggesting next commands.
Principle 2: Build custom CLIs when needed for specific agent tasks, focusing on functionality over perfection for personal use.
If a required CLI doesn't exist, build one tailored to your specific use case. Personal CLIs don't need to be perfect for all edge cases if they are for individual use, prioritizing functionality. Importantly, agent-facing tools should provide meaningful error messages that guide recovery, not just state failure.
Sections
Introduction to Firstmate
An L8 principal engineer at Meta built Firstmate, an open-source project, by wrapping existing tools and stitching them together.
The creator introduces Kun Chen, an L8 principal engineer at Meta, who quit his job to build wrappers for tools like GitHub CLI, Chrome DevTools, and Git worktrees, eventually combining them into an open-source project called Firstmate. This project quickly gained traction, hitting 3,000 stars in two months. The core idea is that in the age of AI agents, adapting software to specific workflows yields the highest productivity.
Firstmate allows users to 'talk to one agent and ship with a crew' by managing a fleet of worker agents.
Firstmate functions as a system where a user (the captain) interacts with a single agent (Firstmate), which then orchestrates a fleet of worker agents. These workers are spawned in separate terminal windows with clean Git worktrees, supervised by Firstmate, and ultimately deliver finished pull requests. The system is nautically themed.
Firstmate is an 'agent distro,' not a traditional application, requiring only a Git clone to set up.
Unlike typical software, Firstmate has no binary, installer, or server. Users simply Git clone the repository, navigate into it, and launch their preferred agent harness. The repository itself is the product, containing agent operating contracts, skill manifests, and numerous helper scripts, primarily in bash.
Firstmate operates under five hard rules to manage crewmate behavior and ensure captain control.
The system enforces five priority-ordered rules: 1. The orchestrator is read-only; only crewmates touch code. 2. Never merge a pull request without explicit captain approval. 3. Never tear down unlanded work to prevent data loss. 4. Crewmates report to Firstmate, which then interfaces with the captain, creating a single point of contact. 5. Report outcomes faithfully, even failures.
Firstmate Demonstration and Architecture
Firstmate uses Git worktrees and delegates tasks to specialized crewmate agents after identifying the problem.
A demonstration shows Firstmate registering a local project, identifying a failing test, and delegating the fix to a crewmate. Behind the scenes, Firstmate clones the project, creates worktrees, analyzes the problem, creates a brief for the crewmate, spawns the agent using scripts like fm-spawn.sh, and monitors completion via fm-session-start. It uses a CLI tool called .treehouse to manage worktrees.
Crewmate agents work autonomously within their own terminal sessions and worktrees.
The demonstration shows crewmate agents working within cmux terminal sessions, operating autonomously to fix issues. Once the task is completed, the session is cleaned up, and Firstmate is alerted.
Firstmate can orchestrate multiple tasks concurrently across different worktrees without conflicts.
The system can handle multiple tasks simultaneously, with Firstmate spinning up distinct terminal instances for three different tasks (e.g., adding features, investigating errors) working on separate Git worktrees, demonstrating its orchestration capabilities.
Firstmate's underlying infrastructure relies on numerous custom-built CLI tools, forming a personal 'agent stack'.
The bootstrap script for Firstmate checks for eleven tools, many created by Kun Chen, such as gh-axi (GitHub CLI wrapper), chrome-devtools-axi (browser automation wrapper), and no-mistakes (validation pipeline with 7.5k stars). This forms a comprehensive personal stack for agent experience (AXI).
Firstmate uses an event-driven system with a zero-token watcher, codifying reasoning into bash scripts.
Instead of traditional heartbeats common in asynchronous systems, Firstmate utilizes a deferred process managed by a script. This approach optimizes token usage by codifying the reasoning process into bash scripts, effectively using AI to automate AI agent thinking work.
Principles for Building AI Workflows
Principle 1: Wrap existing CLIs to tailor them for agent use cases, reducing complexity and round trips.
Wrapping CLIs like GitHub's with tools such as gh-axi creates smaller, more focused outputs that are easier for agents to parse. This reduces the number of agent turns required, minimizes potential failure points, and saves tokens. Examples include pre-computing data and suggesting next commands.
Principle 2: Build custom CLIs when needed for specific agent tasks, focusing on functionality over perfection for personal use.
If a required CLI doesn't exist, build one tailored to your specific use case. Personal CLIs don't need to be perfect for all edge cases if they are for individual use, prioritizing functionality. Importantly, agent-facing tools should provide meaningful error messages that guide recovery, not just state failure.
Principle 3: Verify AI output through automated pipelines instead of supervising every tool call.
Implement validation pipelines like 'no-mistakes' to assess agent work automatically before shipping. Safety is established at the environment level (e.g., disposable worktrees, read-only orchestrator, end-of-cycle validation) rather than through human approval of each action, enabling greater AI autonomy.
Principle 4: Create reusable, generalizable systems and document conventions for automations.
Document conventions and create a single source of truth for automations. Reusable CLIs and wrappers allow systems to share convention layers, reducing the mental overhead of remembering numerous different conventions. This systematization enables learning and building abstractions once, benefiting all repositories.
The Value and Warnings of Custom Agent Stacks
Building custom agent stacks yields significant productivity gains by adapting tools to individual workflows.
This pattern of creating personalized workflows and tooling demonstrably works, offering substantial productivity improvements. AI has lowered the barrier to entry for building such custom solutions.
Be aware of maintenance costs associated with custom tools, including API changes and dependency vulnerabilities.
While AI makes coding cheaper, custom tools incur maintenance costs. These can range from upstream API changes to security vulnerabilities in dependencies. AI can be used to automate parts of this maintenance, such as monitoring and patching.
Robust custom systems are primarily beneficial for parallelized work across multiple agents and tasks.
Complex custom systems are most valuable for users needing to parallelize work across numerous agents and tasks simultaneously, while maintaining control without manually overseeing every action. Simple, single-project use cases may not require such elaborate setups.
Adopt principles and ideas from existing stacks, like Firstmate, rather than copying them wholesale.
Adopting someone else's personal stack means inheriting their specific choices. The goal should be to learn from their knowledge, systems, and CLIs, taking what works and adapting it, rather than blindly integrating pre-built solutions. AI greatly facilitates this personalization process.
Experimentation and iteration are key; perfectionism is unnecessary given the low cost of AI-assisted development.
Developers should not strive for perfectionism as the cost of creating and iterating on AI tools is low. Workflows may be short-lived, but the learnings accumulate, leading to personal growth as a developer. Continuous experimentation is encouraged.
Ask a Question
*Uses 1 Wisdom coin from your coin balance
