ai-fleet 🚀

"Spin up and command a fleet of AI developer agents from your terminal."

---

Table of Contents

• Quick Start
• Installation
• Core Features
• Commands Reference
• Configuration
• Development Setup
• Examples
• Troubleshooting
• Product Requirements

---

Quick Start

# Install from PyPI (when published)
pipx install ai-fleet

# Or install from source (see Development Setup)
uv pip install -e .

# Set up your API key
export ANTHROPIC_API_KEY=sk-...

# Navigate to your project
cd /path/to/your/project

# Initialize AI Fleet in your project
fleet init

# Create your first agent
fleet create fix-auth --prompt "Fix the authentication bug in login.py"

# List running agents
fleet list

# Check logs
fleet logs fix-auth

# Send additional instructions
fleet prompt fix-auth "Make sure to add tests"

# Attach to see live output
fleet attach fix-auth

# Clean up when done
fleet kill fix-auth

---

Installation

From PyPI (when published)

# Using pipx (recommended)
pipx install ai-fleet

# Or using pip
pip install ai-fleet

From Source (Development)

See Development Setup section below.

---

Key Concepts

Project-Based Configuration

AI Fleet works on a per-project basis. Each git repository you want to use AI Fleet with needs to be initialized:

1. One config per project: Configuration lives in .aifleet/config.toml within your project
2. Automatic detection: Commands work from any subdirectory within your project
3. Isolated state: Each project maintains its own agent state and worktrees
4. Team friendly: Configuration can be committed and shared with your team

---

Core Features

🎯 Single Agent Management

• Create individual agents with custom prompts
• Each agent runs in an isolated git worktree
• Full tmux session management
• Real-time CPU/memory monitoring

🚀 Parallel Agent Orchestration

• Fanout: Launch N agents with the same prompt
• Multi: Launch multiple agents with different tasks
• Batch management and cleanup
• Pattern-based operations (glob support)

🔧 Project Integration

• Automatic credential file copying
• Custom setup commands per project
• Git worktree isolation
• Branch naming conventions

📊 Monitoring & Control

• Real-time agent status with CPU/RAM usage
• Log tailing and session attachment
• Interactive prompt sending
• Batch operations

---

Commands Reference

Core Commands

fleet create <branch> [--prompt PROMPT]

Create a new agent on a specific branch.

fleet create fix-auth --prompt "Fix the login authentication bug"

Options:

• --prompt, -p: Initial prompt to send to the agent
• --agent, -a: AI agent to use (default: claude)
• --quick: Skip setup commands for faster creation

fleet list [--grouped]

List all running agents with their status.

fleet list          # Simple table view
fleet list --grouped # Group by batch ID

Shows:

• Branch name
• Session status
• CPU/memory usage
• Runtime duration
• Batch ID (if applicable)

fleet prompt <branch> "<message>"

Send additional instructions to a running agent.

fleet prompt fix-auth "Add unit tests for the changes"

fleet attach <branch>

Attach to an agent's tmux session interactively.

fleet attach fix-auth
# Press Ctrl+B, D to detach

fleet logs <branch> [-n LINES]

View the output logs of an agent.

fleet logs fix-auth          # Last 50 lines (default)
fleet logs fix-auth -n 200   # Last 200 lines

fleet kill <pattern>

Terminate agents matching the pattern.

fleet kill fix-auth           # Kill specific agent
fleet kill "auth-*"          # Kill all matching pattern
fleet kill --batch batch123   # Kill entire batch

Options:

• --batch: Treat pattern as batch ID
• --force: Skip confirmation prompt

Parallel Execution Commands

fleet fanout <count> [prefix] --prompt PROMPT

Create multiple agents with the same prompt.

# Auto-generated batch ID
fleet fanout 5 --prompt "Refactor the authentication module"
# Creates: fanout-a7b9c2d4-A, fanout-a7b9c2d4-B, ...

# Custom branch prefix
fleet fanout 5 auth-refactor --prompt "Refactor the authentication module"
# Creates: auth-refactor-A, auth-refactor-B, ...

Options:

• --agent, -a: AI agent to use
• --quick: Skip setup commands

fleet multi <branch:prompt> [branch:prompt ...]

Create multiple agents with different prompts.

fleet multi \
  fix-auth:"Fix login bug" \
  add-tests:"Add unit tests for auth" \
  update-docs:"Update API documentation"

Each agent gets:

• Its own branch
• Its own worktree
• Its own tmux session
• A different initial prompt

Configuration Commands

fleet init [--type TYPE] [--migrate-legacy]

Initialize AI Fleet in the current project.

fleet init                    # Auto-detect project type
fleet init --type rails       # Initialize as Rails project
fleet init --migrate-legacy   # Import from old global config

fleet config [--edit] [--validate] [--show-origin]

Manage AI Fleet configuration.

fleet config              # Show current project config
fleet config --edit       # Edit project config in $EDITOR
fleet config --validate   # Check configuration validity
fleet config --show-origin # Show where each setting comes from

fleet update [--check] [--force]

Check for and install updates to AI Fleet.

fleet update           # Check and install updates
fleet update --check   # Only check for updates
fleet update --force   # Force check (bypass cache)

The update command automatically detects your installation method (pipx, pip, uv, or source) and uses the appropriate update mechanism.

---

Configuration

AI Fleet uses project-based configuration. Each project has its own .aifleet/config.toml file.

Initializing a Project

# Navigate to your git repository
cd /path/to/your/project

# Initialize AI Fleet
fleet init

# Or initialize with a specific project type
fleet init --type rails  # Rails project with sensible defaults
fleet init --type node   # Node.js project
fleet init --type python # Python project

Configuration Structure

# .aifleet/config.toml - Project configuration
[project]
name = "my-awesome-project"
worktree_root = "~/.aifleet/worktrees/my-awesome-project"

[agent]
default = "claude"
claude_flags = "--dangerously-skip-permissions"

[setup]
credential_files = [
    "config/master.key",
    ".env",
    ".env.local"
]
commands = [
    "bundle install",
    "npm install",
    "bundle exec rails db:create db:migrate"
]

---

Development Setup

Prerequisites

• Python 3.9+
• Git
• tmux
• uv (recommended) or pip

Setting Up From Source

1. Clone the repository

   git clone https://github.com/your-org/ai-fleet.git
   cd ai-fleet

2. Install with uv (recommended)

   # Install uv if you haven't already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create virtual environment and install dependencies
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e ".[dev,test]"

   Or with pip

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e ".[dev,test]"

3. Run tests

   # Run all tests with coverage
   pytest
   
   # Run specific test file
   pytest tests/test_cli.py
   
   # Run with verbose output
   pytest -v

4. Run linting and type checking

   # Linting with Ruff
   ruff check .
   ruff check . --fix  # Auto-fix issues
   
   # Type checking with mypy
   mypy src/

5. Install pre-commit hooks (optional)

   lefthook install

Project Structure

ai-fleet/
├── src/
│   └── aifleet/
│       ├── cli.py           # Main CLI entry point
│       ├── commands/        # Command implementations
│       │   ├── create.py
│       │   ├── list.py
│       │   ├── prompt.py
│       │   ├── attach.py
│       │   ├── logs.py
│       │   ├── kill.py
│       │   ├── fanout.py
│       │   └── multi.py
│       ├── config.py        # Configuration management
│       ├── state.py         # Agent state tracking
│       ├── tmux.py          # Tmux integration
│       ├── worktree.py      # Git worktree management
│       └── utils.py         # Utility functions
├── tests/                   # Test suite
├── pyproject.toml          # Project configuration
└── README.md               # This file

Making Changes

1. Create a new branch

   git checkout -b feature/your-feature

2. Make your changes and add tests

3. Run tests and linting

   pytest
   ruff check .
   mypy src/

4. Commit with descriptive message

   git add .
   git commit -m "Add feature: description"

---

Examples

Example 1: Working on a Bug Fix

# Create agent for bug fix
fleet create fix-login-bug --prompt "Fix the bug where users can't login with email addresses containing '+' symbol"

# Monitor progress
fleet logs fix-login-bug -n 100

# Add clarification
fleet prompt fix-login-bug "Make sure to handle URL encoding properly"

# Review the changes
fleet attach fix-login-bug

# Clean up
fleet kill fix-login-bug

Example 2: Exploring Multiple Solutions

# Launch 3 agents to explore different approaches
fleet fanout 3 refactor-auth --prompt "Refactor the authentication system to use JWT tokens instead of sessions"

# Monitor all agents
fleet list --grouped

# Check specific agent
fleet logs refactor-auth-B

# Keep the best solution, kill the rest
fleet kill refactor-auth-A
fleet kill refactor-auth-C

Example 3: Parallel Sprint Work

# Work on multiple tickets simultaneously
fleet multi \
  fix-432:"Fix user profile image upload bug" \
  feat-433:"Add dark mode toggle to settings" \
  test-434:"Add integration tests for payment flow" \
  docs-435:"Update API documentation for v2 endpoints"

# Check progress on all
fleet list

# Focus on one that needs help
fleet attach feat-433
fleet prompt feat-433 "Use CSS variables for theme colors"

# Clean up completed tasks
fleet kill fix-432
fleet kill test-434

Example 4: Quick Experimentation

# Skip setup commands for faster iteration
fleet create experiment --prompt "Try using Redis for session storage" --quick

# Quick cleanup of all experimental branches
fleet kill "experiment*"

---

Migration Guide

Migrating from Global Configuration

If you've been using an older version of AI Fleet with global configuration (~/.ai_fleet/config.toml), follow these steps:

1. Navigate to your project

   cd /path/to/your/project

2. Run migration

   fleet init --migrate-legacy

3. Review the migrated configuration

   fleet config

4. Remove old global config (optional)

   rm ~/.ai_fleet/config.toml.backup  # After verifying everything works

What's Changed

• Old: Single global config at ~/.ai_fleet/config.toml
• New: Per-project config at .aifleet/config.toml
• Benefit: Work on multiple projects without config switching

---

Troubleshooting

Common Issues

"No agent found for branch"

• Check if the agent is running: fleet list
• Ensure you typed the branch name correctly
• The agent might have crashed - check tmux ls

"Failed to create worktree"

• Ensure repo_root in config points to a valid git repository
• Check if the branch name already exists: git branch -a
• Verify you have write permissions to worktree_root

"Command not found: fleet"

• Ensure the package is installed: pip show ai-fleet
• Check if the scripts directory is in your PATH
• Try using python -m aifleet.cli instead

Setup commands failing

• Run fleet config --validate to check configuration
• Try creating an agent with --quick to skip setup commands
• Check setup command output in logs: fleet logs <branch>

Debug Mode

For verbose output, set the environment variable:

export AI_FLEET_DEBUG=1
fleet create test-branch --prompt "Test"

Manual Cleanup

If agents get orphaned:

# List all tmux sessions
tmux ls | grep ai_

# Manual cleanup
tmux kill-session -t ai_branch-name
rm -rf ~/.ai_fleet/worktrees/branch-name

# Reconcile state file
fleet list --repair  # Coming in next version

---

Product Requirements Document

0 · Elevator pitch

One CLI lets you launch N Claude Code, Codecs, or future LLM agents on isolated git work-trees, stream their logs, and kill them when done.
Perfect for parallel idea exploration (same prompt) or shotgun ticket tackling (different prompts).

Core Building Block: Every agent runs in its own isolated environment:

• 1 agent = 1 git worktree + 1 branch + 1 tmux session
• Automatic setup of credentials and dependencies
• Full isolation between agents (no conflicts)

---

1 · Problem

• Manual setup of git worktree + tmux + agent is slow and error-prone.
• Juggling many branches/ panes breaks flow.
• No lightweight tool tracks which agent is on which task.

---

2 · Goal (MVP scope)

✔ Must-have	❌ Out-of-scope for MVP
create <branch> [--prompt]	Any GUI / dashboard
prompt <branch> "<msg>"	Docker / Nomad orchestration
attach <branch> (tmux)	Prometheus / alerting
logs <branch> tail	Winner-picking, auto-merge
kill <branch>	Fine-grained RBAC
list with CPU/RAM %	Multiple machines
fan-out: fanout N --prompt	Deep Linear automation (phase 2)
multi: multi branch:prompt...	Issue tracker integration (phase 2)

State is persisted in ~/.ai_fleet/state.json.

---

3 · CLI design

Command	Action
fleet create fix-42 --prompt "write failing test"	new work-tree, new tmux session, send prompt
fleet fanout 5 --prompt "refactor auth"	spin 5 agents (auto-generates unique batch ID), creates branches fanout-<UUID>-A1..A5, each with own worktree + tmux session
fleet fanout 5 auth-refactor --prompt "refactor auth"	spin 5 agents with custom branch prefix, creates branches auth-refactor-A1..A5, each with own worktree + tmux session
fleet multi fix-auth:"Fix login bug" add-tests:"Add auth tests" refactor-db:"Clean up DB layer"	spin 3 agents with different tasks, creates branches fix-auth, add-tests, refactor-db each with own prompt
fleet prompt fix-42 "green it"	send extra instruction
fleet logs fix-42 [-n 1000]	tail last lines
fleet attach fix-42	attach interactive
fleet kill fix-42	terminate session & delete work-tree
fleet list [--grouped]	show table, optionally group by batch

Alias: flt executes the same entry-point for muscle-memory speed.

---

3.1 · Fanout Command Details

The fleet fanout command is the core building block for parallel agent orchestration. It supports two modes:

Mode 1: Auto-generated batch ID (default)

fleet fanout 5 --prompt "refactor auth"

• Generates a unique batch ID (e.g., a7b9c2d4)
• Creates branches: fanout-a7b9c2d4-A1 through fanout-a7b9c2d4-A5

Mode 2: Custom branch prefix

fleet fanout 5 auth-refactor --prompt "refactor auth"

• Uses your specified prefix
• Creates branches: auth-refactor-A1 through auth-refactor-A5

Both modes:

1. Create N independent agents, each with:
   • A dedicated git worktree
   • A new branch with the appropriate naming pattern
   • A separate tmux session named after the branch
2. Send the same prompt to all agents simultaneously
3. Track all agents as a batch for easy management

Benefits:

• Auto-generated IDs prevent branch naming conflicts
• Custom prefixes allow meaningful batch names
• Easy batch identification with fleet list --grouped
• Simple cleanup of entire batches with pattern matching

---

3.2 · Multi Command - Working on Different Tasks in Parallel

The fleet multi command is designed for when you have multiple distinct tasks, each requiring its own agent and prompt:

fleet multi fix-auth:"Fix the login bug" add-tests:"Add unit tests for auth module" refactor-db:"Refactor database connections"

This single command:

1. Parses branch:prompt pairs from your input
2. Spins up one agent per task, each with:
   • Its own git worktree
   • A branch with your specified name (e.g., fix-auth)
   • A separate tmux session
   • Your custom prompt as its initial instruction
3. Manages all agents from one CLI

Key Difference: Fanout vs Multi

Mode	Use Case	Prompts	Example
fanout	Same task, multiple approaches	All agents get the SAME prompt	5 agents all trying different ways to "refactor auth"
multi	Different tasks in parallel	Each agent gets a DIFFERENT prompt	Agent 1 fixes bug, Agent 2 adds feature, Agent 3 writes tests

Why Multi Mode?

Perfect for:

• Working through a sprint backlog
• Tackling multiple bug fixes simultaneously
• Exploring different features in parallel
• Letting agents work independently while you review/guide them

The tool handles all the plumbing (worktree setup, credentials, tmux sessions) so you can focus on managing the agents and their progress.

---

4 · Internal file layout

(all paths are overridable in config.toml)

~/.ai_fleet/
├─ config.toml  # global settings (generated on first run)
├─ state.json   # live agent registry (CLI updates atomically)
└─ worktrees/   # default parent dir for auto-created worktrees

4.1 · config.toml keys

Key	Default	Purpose
repo_root	~/code/my-project	Monorepo root for worktree creation
worktree_root	~/.ai_fleet/worktrees	Where branches are checked out
tmux_prefix	ai_	All tmux sessions are named <prefix><branch>
default_agent	claude	claude | codecs (future runtimes)
claude_flags	--dangerously-skip-permissions	Extra flags appended to claude
credential_files	[]	Files to copy from main repo to each worktree
setup_commands	[]	Commands to run after worktree creation

Create or edit this file by running:

fleet config edit

4.1.1 · Worktree Setup Configuration

For projects that need credentials or setup steps (like Rails apps), configure in config.toml:

# Copy credential files from main repo to each worktree
credential_files = [
    "config/master.key",
    "config/credentials/development.key",
    ".env",
    ".env.local"
]

# Run these commands in each new worktree (executed in order)
setup_commands = [
    "bundle install",
    "npm install",
    "bundle exec rake db:create db:migrate",
    "bundle exec rake assets:precompile"
]

# Optional: Quick setup mode (skip heavy commands)
quick_setup = true  # When true, only copies files, skips setup_commands

Note: Setup commands run in the worktree directory. Use && to chain commands or check success.

4.2 · state.json schema (MVP)

[
  {
    "branch": "fix-42",
    "worktree": "/home/nacho/.ai_fleet/worktrees/fix-42",
    "session": "ai_fix-42",
    "pid": 12345,
    "batch_id": "manual-2025-05-31",
    "agent": "claude",
    "created_at": "2025-05-31T23:05:00Z"
  }
]

CLI commands never rely solely on this file: fleet list --repair reconciles real tmux sessions against disk if the file gets out of sync.

---

5 · Tech stack snapshot (MVP)

Layer	Choice	Rationale
Language	Python 3.11 + Click	fast to iterate, easy to refactor
Proc supervisor	tmux	ubiquitous, allows send-keys
Data store	Flat JSON + TOML	no DB dependency
Metrics	psutil	per-PID CPU/RAM collection
Packaging	PyPI ai-fleet	installs fleet + flt binaries

---

6 · Key interactions / happy-path demo

# install
pipx install ai-fleet
export ANTHROPIC_API_KEY=sk-...

# explore 3 versions of the same idea
fleet fanout 3 auth-refactor --prompt "refactor auth flow"

# parallel sprint - work on different tasks
fleet multi fix-auth:"Fix login bug" add-tests:"Add auth module tests" update-docs:"Update API documentation"

# monitor
fleet list --grouped        # see CPU/RAM per agent
fleet logs fix-auth -n 200  # tail
fleet prompt fix-auth "run tests"

# manual dive-in
fleet attach auth-refactor-A2

# clean everything from a batch
fleet kill auth-refactor-A*    # glob supported

---

7 · Success metrics

KPI	Target
fleet create → first agent reply	≤ 10 s
Fan-out launch (N=5)	≤ 20 s
Orphaned worktrees after kill	0 %
CLI memory footprint	~0 MB
Test suite ✔ on CI	100 %

---

8 · Roadmap after MVP

• Ticket integration – fetch task descriptions from Linear/GitHub/Jira for fleet multi
• REST/WebSocket shim – expose same ops for a SwiftUI dashboard.
• Cost tracking – poll /cost (Claude) & usage logs; Prometheus exporter.
• Linear / GitHub webhooks – auto-spawn agents on ticket creation.
• Container mode – optional Docker/Nomad backend for hard CPU/RAM caps.
• Winner-picker – batch command to run tests, rank branches, highlight best.
• Merge-assistant – create PRs automatically and comment results.

---

9 · Open questions

Area	Question
Concurrency	Hard cap on simultaneous Claude/Codecs sessions per org?
Isolation	When to require Docker to avoid RAM blow-ups?
Auth	Stick with env vars or integrate doppler/1Password secrets?
Branch hygiene	Enforce prefix patterns (fix-, feature-), auto-delete merged?

---

10 · Namespace & packaging

Thing	Value
PyPI	ai-fleet
Import path	aifleet.*
Executables	fleet, flt
GitHub repo	github.com/your-org/ai-fleet

Tip: publish a 0.0.0 stub to reserve the PyPI name before going public.

---

11 · Project-Specific Setup Examples

Rails Project

credential_files = [
    "config/master.key",
    "config/credentials/development.key"
]

setup_commands = [
    "bundle install",
    "RAILS_ENV=test bundle exec rails db:create db:migrate",
    "RAILS_ENV=test bundle exec rails assets:precompile"
]

Node.js Project

credential_files = [".env", ".env.local"]

setup_commands = [
    "npm install",
    "npm run build"
]

Python Project

credential_files = [".env", "secrets.json"]

setup_commands = [
    "uv sync",  # or "pip install -r requirements.txt"
    "python manage.py migrate"  # for Django
]

Tip: Use fleet config validate to check your setup configuration before creating agents.

---

12 · License

MIT – do what you want, just don't sue. (Change if you prefer Apache-2.0 or GPL.)