A dead simple multi-agent orchestration tool. Fleet runs multiple Claude Code agents in Docker containers, coordinated through git. You plan the work, agents develop, review, test, and document in parallel.
No frameworks, no custom protocols. One bash script, git as the shared state, Docker for isolation.
I got tired of context switching between 3-5 parallel Claude Code sessions. The workflow was: plan a task, kick it off, wait, switch to another, come back, review, open a PR, repeat. Meanwhile AI writes the code and reviews it, so why am I still the one juggling browser tabs and opening PRs?
Fleet moves the entire loop (planning, development, review, QA) onto your machine. You plan once, agents handle the rest. When they're done, you get clean, reviewable branches per task instead of one giant PR. Or you can simply merge the whole project in a single command.
Read the full story: Why I Built Fleet
In short:
- Less context switching. One project, one monitor, multiple agents working in parallel.
- Everything lives in git. Tasks are files. Agents coordinate through commits. Full paper trail.
- Agents run in Docker. Full YOLO mode inside containers. Your machine stays clean.
- Human stays in control. You plan interactively, start/stop agents anytime, create tasks on the fly.
- Clean output. Each task gets its own branch. Merge them individually or put them up for human review.
- Docker-level isolation for full YOLO mode
- Zero framework dependencies (built for Claude Code, but the coupling is shallow. It's one
claudecall inagent_loop.shplus output parsing. Swapping in a different CLI is a small patch) - Human plans/designs the work, AI breaks it down into chunks of work
- No orchestration agent, no communication beyond moving tasks. However, if you want an orchestration agent, simply tell Claude to start and monitor the fleet. It usually does it pretty well.
Fleet organizes work into projects. A project is a goal you want to reach. Fleet breaks it into tasks and assigns agents to work on them. A project is deliberately fluffy. It can be anything from a single task to a full product.
You (human) Fleet Agents (in Docker)
| | |
|-- fleet new ----->| |
|-- fleet design -->| (interactive planning) |
|-- fleet start --->|-- launches containers -->|
| | |-- plan creates tasks
|-- fleet monitor ->| |-- developers pick tasks
| | |-- reviewers review work
| | |-- QA validates quality
|-- fleet close --->|-- merges branches ------>|
| | |
The task board is a set of directories in .fleet/tasks/:
.fleet/tasks/
drafts/ # unrefined task ideas (plan agent refines these)
available/ # tasks waiting to be picked up
in_progress/ # tasks being worked on (locked by an agent)
in_review/ # tasks submitted for review
completed/ # done
Agents claim tasks by writing a lock into the task file and committing it. Reviewers can approve or reject. Rejected tasks go back to available with feedback attached. No human intervention needed until you want it.
The git workflow uses a bare upstream repo inside .fleet/upstream.git/. Agents push and pull from there. Each task gets its own branch. When you close a project, fleet merges everything back to main.
# Clone the repo
git clone https://github.com/cgraf00/fleet.git ~/.fleet
# Option A: Add to PATH
export PATH="$HOME/.fleet/bin:$PATH" # add to your shell profile
# Option B: Run install.sh to create a symlink
~/.fleet/install.sh # links to /usr/local/bin/fleet- Docker (running)
- Claude Code CLI (
claude) or anANTHROPIC_API_KEY - Git
# Go to your repo
cd my-repo
# Start a new project (sets up fleet tooling on first run)
fleet new "Link shortener with analytics"
# Edit the project file to describe what you want
# Or use the interactive designer:
fleet design
# Launch the full fleet. The planning agent will create tasks.
fleet start
# Watch progress
fleet monitorWhen agents are done:
# Review the project status
fleet status
# Close the project (stops agents, archives, merges to main)
fleet close
# Start another project in the same repo
fleet new| Command | Description |
|---|---|
fleet new "<name>" |
Start a new project (sets up tooling + integration branch). |
fleet design |
Interactive project designer (optional). |
fleet design --quick "desc" |
Quick one-shot design from a description. |
fleet start |
Launch full fleet from config. |
fleet start <role> |
Start a specific role (e.g., fleet start plan). |
fleet start <role> --count N |
Start N agents of a role. |
fleet start <role> -m <model> |
Override model for this role. |
fleet monitor |
Live dashboard. Refreshes every 5s. |
fleet close |
Stop agents, archive project, merge to main. |
fleet merge |
Archive project and merge integration branch to main. |
| Command | Description |
|---|---|
fleet stop <role|all> |
Stop agents by role or all. |
fleet status |
Show running agents and task board. |
fleet logs |
Show recent logs for all agents. |
fleet logs -f |
Follow logs (like docker logs -f). |
fleet logs <agent-id> |
Logs for a specific agent. |
fleet task "description" |
Create a draft task. Use --ready to skip drafts, --next to insert at front. |
fleet unlock <task> |
Clear a stale lock on a task. |
fleet build |
Rebuild Docker image. |
fleet pull |
Pull agent work from upstream into local branch. |
fleet push |
Push local commits to upstream (visible to agents). |
fleet sync |
Pull + push (shorthand). |
fleet install |
Update .fleet/ tooling from your local fleet install. |
| Role | What it does |
|---|---|
| plan | Reads project.md, creates tasks, updates progress. |
| developer | Picks tasks, writes code, commits on task branches. |
| reviewer | Reviews submitted work, approves or rejects with feedback. |
| qa | Validates the integrated product, creates follow-up tasks for issues. |
| docs | Maintains living project documentation (architecture, stack, features, learnings) that is automatically injected into every agent's prompt. |
| research | Investigates topics, writes findings to .fleet/output/. |
| critique | Reviews outputs for quality (for research projects only). |
Custom roles: create .fleet/roles/<name>.md and start with fleet start <name>.
Fleet reads .fleet/config.yaml in the project:
# Default model for all agents
model: claude-opus-4-6
# Fleet composition (used by fleet start with no args)
fleet:
plan: 1
developer: 3
reviewer: 2
qa: 1
docs: 1
# QA settings
qa:
mode: normal # normal | strict| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
API key. Optional if Claude subscription credentials exist. |
MODEL |
Override model for all agents. |
FLEET_HOME |
Override fleet install location (auto-detected by default). |
Your machine
|
|-- fleet (bash script)
| |-- manages Docker containers
| |-- manages .fleet/ directory
| |-- manages upstream.git bare repo
|
|-- .fleet/
| |-- project.md # what you're building
| |-- progress.md # current state
| |-- config.yaml # fleet configuration
| |-- tasks/ # the task board
| |-- docs/ # living documentation (auto-injected into agents)
| |-- output/ # research findings, QA reports
| |-- roles/ # agent role prompts
| |-- upstream.git/ # bare repo for agent coordination
| |-- Dockerfile # agent container image
| |-- agent_loop.sh # container entry point
|
|-- Docker containers (one per agent)
|-- clone from upstream.git
|-- run claude CLI
|-- push results back
Why git for coordination? No extra infrastructure. Agents already know how to use git. Every action is a commit, so you get a full audit trail. If something goes wrong, git log tells you what happened.
Why Docker? Agents run with full permissions inside their container. They can install packages, run builds, execute tests. Your machine stays untouched. If an agent does something weird, stop it and the container is gone.
Automatic documentation: The docs agent observes what's been merged and maintains structured documentation in .fleet/docs/ covering architecture, tech stack, features, and learnings. These docs are automatically injected into every agent's prompt on each iteration, so agents always have up-to-date context about the project without you having to explain it. The docs agent only documents what's actually implemented (code on the integration branch), never aspirations or intent.
Idle detection: Agents output IDLE: <reason> when they have nothing to do. The agent loop detects this and backs off linearly (30s, 60s, 90s... up to 5 minutes). No busy-waiting, reduced polling overhead.
Adding a new agent role is one file:
# Create a role prompt
cat > .fleet/roles/security.md << 'EOF'
You are a **security agent**. Your job is to review code for security
vulnerabilities and create tasks for issues you find.
## What You Do
- Review completed tasks for OWASP top 10 vulnerabilities
- Check dependencies for known CVEs
- Create tasks in .fleet/tasks/available/ for issues found
EOF
# Start it
fleet start securityThe base protocol (task picking, locking, IDLE detection) is inherited automatically from .fleet/roles/base.md.
Fleet isn't limited to writing code. The research agent investigates topics and writes structured findings to .fleet/output/. You can use this for any knowledge work:
- Describe what you want to learn in
project.md - Start a plan agent to break it into research tasks
- Start research agents to investigate
- Start a critique agent to review findings
- Results end up in
.fleet/output/as markdown files
No code needs to be written. The task board and agent coordination work the same way.
If you have a Claude Pro/Team subscription and the Claude desktop app or Claude Code installed, fleet can use those credentials instead of an API key.
On macOS, Claude stores credentials in your keychain and you can extract them using this command:
security find-generic-password -s "Claude Code-credentials" -w > ~/.claude/.credentials.json
Fleet reads ~/.claude/.credentials.json automatically, no ANTHROPIC_API_KEY needed. Before starting agents, fleet checks that the token hasn't expired.
If you're using an API key instead, set it in your environment or in .env in your project root:
export ANTHROPIC_API_KEY=sk-ant-...- macOS/Linux only. The bash script and Docker setup haven't been tested on Windows.
- Claude Code only. Agents use the
claudeCLI. Other LLM providers aren't supported yet. - Merge conflicts. If agents edit the same file on different task branches, you'll need to resolve conflicts at merge time. Fleet detects this and warns you.
- No resumable agents. When a container stops, uncommitted work is lost. Agents are instructed to commit early and often, but it's not guaranteed.
- Git noise. Task board operations create commits. This is by design (audit trail), but it means your git history will have coordination commits mixed in with code commits.