Skip to content

nachoal/ai-fleet

BranchesTags

Repository files navigation

ai-fleet 🚀

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

Table of Contents

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.)

About

AI Agent fleet manager for parallel agentic systems like claude code and codex

Topics

tmux llm claude-code

Resources

Readme

License

MIT license
Activity

Stars

47 stars

Watchers

3 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages