Guide

How to Run Multiple Claude Code Agents at the Same Time

Name: Fleet
Author: Fleet

Running a single Claude Code session works fine for one task. The problem is that most software projects have several streams of work happening at once — a feature branch, a bug fix, a code review — and serializing all of that through one agent session creates a bottleneck that defeats the purpose of automation.

This guide shows how to configure and launch multiple Claude Code agents in parallel using Fleet, a self-hosted Go binary that manages agent sessions through tmux. Each agent gets its own context, its own working directory, and its own run-time budget. You do not need cloud infrastructure or Docker.

Before you start

tmux installed and available on your PATH
Claude Code (`claude`) installed and authenticated
Fleet binary installed (see fleetctl.ai for install instructions)
A Git repository with a `.fleet/config.yaml` file

1

Initialize Fleet in your repository

Run fleet init inside your repository. This creates a .fleet/config.yaml file with a starter agent definition. You will edit this file to define each agent you want to run.

cd /path/to/your/repo
fleet init

2

Define multiple agents in config.yaml

Open .fleet/config.yaml and add an entry for each agent. Give each agent a unique name, a role, and optionally a model. Roles like backend-developer, frontend-developer, and qa-engineer determine which skill directives Fleet injects into the agent's handbook prompt. Generic strings like developer or qa inject nothing — use the specific role names.

agents:
  - name: backend-dev
    role: backend-developer
    department: engineering
    reports_to: tech-lead
    model: claude-opus-4-5
  - name: frontend-dev
    role: frontend-developer
    department: engineering
    reports_to: tech-lead
    model: claude-sonnet-4-5
  - name: qa-agent
    role: qa-engineer
    department: engineering
    reports_to: tech-lead
    model: claude-sonnet-4-5

3

Start all agents at once

Use fleet agent start --all to launch every agent defined in config. Each agent gets its own tmux session. Fleet sets environment variables like FLEET_AGENT_NAME and FLEET_AGENT_ROLE automatically so agents know their context.

fleet agent start --all

4

Or start a specific team

If you have organized agents into teams in your config, you can start just that team. This is useful when you only want to activate a subset of agents for a particular sprint or workflow.

fleet agent start --team backend

5

Check status across all running agents

Use fleet status to see which agents are active and what model they are using. Status is derived from live tmux session state, not from a database, so it always reflects reality.

fleet status

Common pitfalls

Agents share the same Git working directory by default. If two developer agents modify the same files concurrently you will get merge conflicts. Use git worktrees to isolate them (see the parallel-agents-git-worktrees guide).
Running many Opus agents simultaneously can exhaust your Anthropic rate limits quickly. Use `max_concurrent` per agent to cap parallelism and keep runaway sessions in check.
tmux session names are derived from the repo and agent name (e.g. `agent-team-<repo>-<name>`). If you rename an agent in config, Fleet treats it as a new agent and the old session remains orphaned until you manually kill it. Use `fleet agent attach <name>` rather than hardcoding session names.
fleet agent start --all will try to start agents that are already running. Fleet detects existing sessions and skips them, but check `fleet status` first to avoid confusion.

When Fleet is the right tool

Fleet is the right tool when you have at least two streams of work that can proceed independently and you want them automated without babysitting each session. It is less useful if you are still figuring out what the agent should do — get one agent working reliably on a single task before scaling to a fleet. If your work is purely sequential (step A must finish before step B starts), a single agent with a long prompt is simpler.

Frequently asked questions

How many agents can I run at once?

There is no hard limit in Fleet. The practical ceiling is your Anthropic rate limit and the CPU/memory of the machine running tmux. Most teams find 4-8 concurrent agents is a reasonable working set.

Do I need a separate API key per agent?

No. All agents share the same Claude credentials. Fleet does not manage API keys — it manages the sessions that use them.

Run your first agent fleet

One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.

See how it works Install Fleet