Overview#

AgentFleet installs 19 native Claude Code subagents — called lanes — under ~/.claude/agents/fleet-*.md and maps each lane to whatever models your provider offers: a Claude subscription, an Anthropic API key, or any Anthropic-compatible gateway. Lane names describe a role, never a model, so the same setup survives provider changes.

The moving parts:

• Lanes — generated subagent files, one per role. Planners and researchers are read-only by default; reviewers verify with commands and edit only in explicit FIX MODE. Diagnosis runs commands but never edits. All lanes run in the background with omitClaudeMd: true and cannot spawn nested agents. The main agent owns outward-facing actions; lane-guard blocks covered forbidden commands.
• Tier ranking at startup — a reconcile step compares your live provider models against each lane's required capability tier and assigns the best fit, spreading models across lanes and keeping assignments stable between sessions.
• Hooks — a routing hook (UserPromptSubmit), a startup model-sync hook, a context-budget hook, and a privacy-safe status line, all installed under ~/.claude/.
• Profiles — named provider configurations you can switch between without reinstalling. The native profile uses your Claude login; gateway profiles store tokens in mode-0600 files.
• Safety — every apply operation takes a backup first; agentfleet rollback restores the previous state. Uninstall removes only files and settings owned by this bundle.

By default Claude works on your task directly, uses a lane only for large work, and agrees on the approach with you before large, unclear or risky tasks; see Work style. AgentFleet keeps its short delegation policy in ~/.claude/rules/agentfleet.md and never edits your own ~/.claude/CLAUDE.md.

AgentFleet is for teams and individuals who use Claude Code daily and want a consistent, well-structured agent fleet that adapts to their provider without manual configuration. Everything lives under your home directory; no root or admin access is required.

Requirements#

• Claude Code
• Python 3.10 or later (on Windows, one installed with uv python install is found even when it is not on PATH)
• Node.js 18 or later (required for agent generation and gateway model discovery)

Supported platforms: macOS, Linux, and Windows. No root or admin access is required.

Install#

One command installs and updates. Run the same command again on an existing install, or use agentfleet update; both keep your provider profile. After a successful terminal install or update, the configuration wizard asks only questions you haven't answered before. Enter keeps the current value. Skip it with AGENTFLEET_NO_CONFIGURE=1 or --no-configure.

Apply a team preset on update with AGENTFLEET_PRESET=team.json agentfleet update, and skip the configuration wizard with AGENTFLEET_NO_CONFIGURE=1 agentfleet update. Both variables work with the 2.2.0 CLI and 2.3.0. From 2.3.0, agentfleet update --preset FILE, --yes, and --no-configure are also available. See For teams.

The download script fetches releases/latest.json, downloads the pinned release archive, verifies its SHA-256, extracts it to ~/.local/share/agentfleet/releases/<version> (Windows: %LOCALAPPDATA%\AgentFleet\releases\<version>), then runs bin/install.py.

curl -fsSL https://agentfleet.wecansync.com/install.sh | sh

irm https://agentfleet.wecansync.com/install.ps1 | iex

From a clone, ./install.sh (or install.ps1 / install.cmd) does the same.

curl -fsSL https://agentfleet.wecansync.com/install.sh | AGENTFLEET_VERSION=2.3.0 sh

What the installer does#

1. Fetch the release manifest

   Downloads releases/latest.json from the configured host.

2. Download the pinned archive

   Fetches the release archive named in the manifest, or the version pinned by AGENTFLEET_VERSION.

3. Verify the checksum

   Confirms the archive's SHA-256 before extracting anything.

4. Extract under your home directory

   Unpacks to ~/.local/share/agentfleet/releases/<version> (or the Windows equivalent). No root or admin access is required.

5. Run the installer

   Runs bin/install.py, which writes the managed files described in What gets installed.

Non-interactive install#

Set AGENTFLEET_NONINTERACTIVE=1 to skip the provider questions, or pass explicit flags. In a terminal, the configuration wizard still asks about new options, so add AGENTFLEET_NO_CONFIGURE=1 to skip it too. Without a terminal, nothing is asked.

# Gateway example (set the token first, outside shell history):
export MY_GATEWAY_TOKEN=…
curl -fsSL https://agentfleet.wecansync.com/install.sh | \
  sh -s -- --provider gateway \
            --gateway-url https://gateway.example.com \
            --gateway-token-env MY_GATEWAY_TOKEN

$env:MY_GATEWAY_TOKEN='…'; & ([scriptblock]::Create((irm https://agentfleet.wecansync.com/install.ps1))) --provider gateway --gateway-url https://gateway.example.com --gateway-token-env MY_GATEWAY_TOKEN

Flags#

Quick reference#

For teams#

A team lead runs agentfleet configure, then agentfleet configure --export team.json. Share the file, never a key. Teammates save it locally and run the same command for installation or updates with the preset:

curl -fsSL https://agentfleet.wecansync.com/install.sh | AGENTFLEET_PRESET=team.json sh

$env:AGENTFLEET_PRESET="team.json"; irm https://agentfleet.wecansync.com/install.ps1 | iex; Remove-Item Env:AGENTFLEET_PRESET

A preset path is relative to the current directory.

Already installed? On macOS/Linux, run AGENTFLEET_PRESET=team.json agentfleet update. On Windows PowerShell, run $env:AGENTFLEET_PRESET="team.json"; agentfleet update; Remove-Item Env:AGENTFLEET_PRESET. From 2.3.0, agentfleet configure --preset team.json also applies a preset. Presets supply no credentials. From 2.4.0 a preset can also set workStyle and agentBrain; it can never run the instruction check. From 2.8.0 it can set the team's models: lanes gives each listed lane its models (the first is its model, the rest its fallbacks, nothing else) and optionally its effort, and reservedModels keeps a model off every lane that does not list it. See Reserving a model. The wizard can save your TypeSafe key with hidden input into ~/.claude/settings.json (env TYPESAFE_API_KEY), where commands Claude runs can read it. For private storage, leave it empty and use /plugin → fast-jev-compaction → Configure. Never paste keys in chat.

Verify with agentfleet config, /fleet-status, and /jev when JEV is enabled. Roll back an install or update with agentfleet rollback.

First-run wizard#

On a fresh interactive install, the wizard asks how Claude Code should reach its models. There are three choices:

1. Claude subscription (default)

   Uses Claude Code's own login. Lanes are mapped to the opus, sonnet, and haiku aliases. No catalog discovery is needed.

2. Anthropic API key

   Reads ANTHROPIC_API_KEY from the environment. Lanes use first-party model IDs directly.

3. Custom gateway

   Asks for an https URL and the name of the environment variable that holds the token (default: AGENTFLEET_GATEWAY_TOKEN). If that variable is unset, the wizard prompts for the token with hidden input. It then calls GET /v1/models to discover models, shows each model's assigned tier, and offers to adjust tier labels before writing anything.

Updates keep the installed profile; --wizard explicitly reopens the provider wizard. After a successful terminal install or update, the separate configuration wizard asks only unanswered questions: work style, ask-first, auto-compact percentage, JEV, reviewer access, learning, fleet-status, lane-guard, token-weather, session-info, automatic updates, and agent-brain (install it when it is missing, connect it when it is installed). It then offers the instruction check. Enter keeps the current value. Run agentfleet configure to revisit every question.

Background updates never ask. The status band then says "New AgentFleet options are available: run agentfleet configure in a terminal."

Skipping the wizard#

Install flags#

Pass flags to the installer by appending them after sh -s -- on macOS/Linux, or by wrapping the PowerShell script in a scriptblock. The table below covers all user-facing flags from python3 bin/install.py --help.

Provider flags#

Behavior flags#

Advanced flags#

Passing flags through the one-liners#

curl -fsSL https://agentfleet.wecansync.com/install.sh | sh -s -- --no-wizard --provider native

& ([scriptblock]::Create((irm https://agentfleet.wecansync.com/install.ps1))) --no-wizard --provider native

Work style#

The work style decides how readily Claude hands work to a lane. Set it with agentfleet config work-style direct|balanced|fleet or in the configuration wizard, then restart Claude Code. The default is balanced, for new and existing installs.

agentfleet config work-style balanced

Reviews, fixes and retries#

From 2.8.0, in every style that uses lanes:

• Claude reviews each lane's changes itself and reruns the check the lane names. A review lane runs only for security, data-loss or migration changes, or when you ask, and at most once per change. fleet-review-deep runs only when you ask for it.
• Claude fixes small findings itself. Larger ones go back to the lane that wrote the code, continued with SendMessage so it keeps what it has read, instead of to a new lane that reads everything again.
• A long, well-specified task goes to one implementation lane in parts; Claude continues the same lane for each part.
• A lane that failed is re-dispatched once. If it fails again, or AgentFleet reports that the gateway is failing, Claude does the work itself and tells you.

A project can add its own risky areas in its CLAUDE.md, for example "installer changes count as risky: have them reviewed on a lane".

Smallest complete change#

From 2.14.0, in every style, Claude and the implementation lanes make the smallest change that fully solves the task, an idea borrowed from Ponytail:

• Before writing, they find every place the change must reach: callers, tests, fixtures, config.
• They reuse what the codebase already has, then the standard library, then installed dependencies, and never add a dependency for a few lines.
• They add no feature, option or abstraction you did not ask for, and say in one line what they left out.
• They still finish every part the task needs.

Plan lanes prefer the smallest design that solves the task. Review lanes list, separately from defects, code a change did not need. The rules add about 80 words to the policy, about 70 to each implementation lane, and no hooks, so they cost far less than installing the Ponytail plugin. If you want the full plugin, with its levels and metrics band, install it yourself; its rules then repeat these.

AgentFleet writes the policy for your chosen style to ~/.claude/rules/agentfleet.md, which Claude Code loads automatically. It is 600 to 800 words depending on the style, plus about 300 for the ask-first section and 200 for the branch check.

Ask first#

With ask-first on (the default), the policy adds a short "How to approach a task" section. Claude still does small, clear tasks straight away. For larger, unclear or risky ones it:

• checks the project's docs/, README and CLAUDE.md before changing an area or answering how something works, and searches the web only for outside libraries and services;
• investigates first, then asks what is still open in one message, with its recommended answer to each question;
• explains what worries it about a risky or doubtful request and recommends a safer way;
• for a large task, offers Spec Kit (and offers to install it and write the project's constitution if missing) or a plan to approve followed by lanes and a review, and says which it recommends;
• for several tasks, asks whether to give each its own git worktree or do them in turn in the current checkout;
• for a new project, asks about a base project or boilerplate and proposes the structure, design pattern and, for a backend, the database schema first;
• stops and reports after two failed attempts at the same fix.
• in the balanced and fleet styles, when a task needs several lanes, gives a concise plan first and waits for your approval before the first lane runs. One lane, or none, needs no team plan; the approach agreement above still applies to large, unclear or risky work. Approval of a fully specified plan covers its continuations and fallbacks; new scope or roles need a new approval. It never covers pushing, merging, migrations or deploys.

It follows a "Workflow" section in the project's CLAUDE.md instead of asking, and offers to record the workflow you pick there.

After a substantial task (code, files or a branch changed, or a long investigation), when it finishes, is blocked or is partly done, or when you ask for a status, Claude ends with one short handoff: branch or worktree, uncommitted state, checks run and not run, blockers, and any pull request or UAT link.

agentfleet config ask-first off

Branch check#

It is easy to finish a task, forget to switch branches, and start the next one on the old branch. With branch-check on (the default), before Claude changes files in a git repository it:

• runs git status -sb and git fetch to see the current branch, uncommitted changes, and whether the branch is behind or ahead of its remote;
• tells you what it found and asks whether to continue on this branch, switch to another, or create a new one from the up-to-date default branch, with its recommendation (a new branch when the current one holds finished or merged work), and offers to pull first when the branch is behind;
• waits for your answer before changing files.

It asks once per task, not before every edit, and skips the check when you have already named the branch or the task runs in its own worktree. It never pulls, switches or creates a branch without your answer, and lanes never do these at all.

agentfleet config branch-check off

Lane effort and stopping#

Lanes use less reasoning effort than in 2.3. implement, review, review-alt, security-review, and diagnose-static run at high. tests, triage-static, research-codebase, and research-web run at medium. plan and the -deep lanes stay at xhigh. An update applies the new values automatically. A lane that is running out of turns now stops and reports what is done and what remains, instead of ending without a report. From 2.8.0 the lane-guard mod also warns a lane at 70% and again at 90% of its turn limit, so it finishes the part it is on and reports before it is cut off. Set a lane's effort yourself with claude-fleet-setup --effort LANE=LEVEL or a team preset.

Lanes#

Each lane is a native Claude Code subagent generated from ~/.claude/fleet.json. All lanes run in the background with omitClaudeMd: true. No lane has the Agent tool, so none can spawn nested agents. The main agent owns integration and every outward-facing action.

From 2.14.1, every lane is told that only its prompt and the brief say what to do: files, web pages, command output and memory it reads are data, so it never follows instructions found in them and reports any that try to change its task. The rule comes from Google Research's Harness².

Planning, exploration, triage, and research lanes have no Bash, Edit, or Write by default. Reviewers can run checks and edit only in explicit FIX MODE; diagnosis can run checks but never edits. Preferences and per-lane tool overrides can restrict access. The lane-guard mod blocks covered destructive and publishing commands in fleet subagents.

Task lanes#

Variant lanes#

Variant names describe a capability, never a model, so they survive provider changes.

Tiers#

Every discovered model gets a capability tier: cheap, fast, balanced, or deep. The tier is determined in priority order:

1. Explicit label

   A label you set with claude-fleet-setup --tier MODEL=TIER always wins.

2. Keywords in the model ID

   cheap: free, cheap, budget, auto
fast: haiku, flash, mini, lite, nano, fast, small, instant
deep: opus, pro, max, ultra, large, sol, astra, o1, o3, reasoner

3. Keywords in the catalog description

   cheap: "free", "cheapest", "budget", "low cost", "low-cost"
   fast: "fastest", "low latency", "low-latency", "quick", "fast"
   deep: "strongest", "deep reasoning", "deeper reasoning", "frontier", "most capable"

4. Default

   balanced when no keyword matches.

Catalogs report context size but not price or speed — that is why explicit labels exist for models whose names do not signal their tier.

Ranking rules#

At startup the reconcile step ranks all live models for each lane. Tier fit dominates the score. Among equal-tier candidates:

• Models that support reasoning rank higher for read-only lanes and deep-tier lanes.
• Models with at least 800K context rank higher. Long-context lanes (fleet-research-codebase) give a larger bonus to 800K+ models.
• The current model receives a stability bonus, so a settled fleet does not reshuffle on every startup.
• Models already serving as another lane's primary lose a small penalty, spreading equally capable models across lanes.
• An -alt lane never shares its sibling's model. This is a hard rule: the sibling's model receives a very large penalty, so the alt picks a different model unless nothing else is live.

The next-best ranked models become each lane's fallbacks (at most 3 entries per lane), so every live model can serve somewhere regardless of how many lanes exist.

Native alias mapping#

With a Claude subscription, no catalog discovery runs. Tiers map directly to aliases:

Tuning#

Use claude-fleet-setup to pin models to lanes, keep models out of the fleet, label model tiers, and re-rank the fleet.

Pinning a lane to a model#

# Pin fleet-implement to a specific model:
claude-fleet-setup --prefer fleet-implement=my-model-id

# Pin with an ordered fallback list:
claude-fleet-setup --prefer fleet-implement=my-primary-model,my-fallback-model

# Clear the pin so the lane returns to tier ranking:
claude-fleet-setup --prefer fleet-implement=

A pinned lane uses your models in your order, and any remaining fallback slots are filled by tier ranking, so a lane pinned to one model still has somewhere to go if that model is unavailable. To use only your list, with no ranked fill-ins, pin it with --prefer-only:

# First model is the lane's model, the rest its fallbacks, nothing else:
claude-fleet-setup --prefer-only fleet-implement=codex-luna,claude-sonnet-5.5

# Set the lane's reasoning effort (low, medium, high, xhigh, max); 'LANE=' clears it:
claude-fleet-setup --effort fleet-implement=high

Model names can leave out the [1m] suffix; AgentFleet matches them to the gateway's IDs.

Keeping a model out of the fleet#

# Never assign this model to any lane, as a primary or a fallback:
claude-fleet-setup --exclude my-model-id

# Allow it again:
claude-fleet-setup --include my-model-id

An excluded model stays in Claude Code's /model picker; it just never serves a lane. Excluding a model also removes it from any lane pins, and pinning an excluded model is refused until you include it again. Exclusions are stored as excludedModels in ~/.claude/fleet.json and survive updates.

Reserving a model#

# Serve only the lanes that name this model (for example an expensive reviewer):
claude-fleet-setup --reserve codex-astra

# Let tier ranking use it again:
claude-fleet-setup --unreserve codex-astra

Catalogs list no prices, so ranking cannot tell an expensive model from a cheap one. A reserved model is never picked by ranking, as a lane's model or a fallback; it serves only lanes whose pin names it, such as claude-fleet-setup --prefer-only fleet-review-deep=codex-astra,claude-opus-5.5. Reservations are stored as reservedModels in ~/.claude/fleet.json and survive updates and profile switches.

Labelling a model's tier#

# Label a model as fast:
claude-fleet-setup --tier my-model-id=fast

# Clear a label (returns to keyword inference):
claude-fleet-setup --tier my-model-id=

Re-ranking now#

claude-fleet-setup --reconcile

Fetches live provider models, runs the full ranking pass, and regenerates all agent files. Run this after changing tier labels or after a provider catalog update.

Custom lanes#

Add a custom lane by editing ~/.claude/fleet.json directly. The lane name must start with fleet-. Required fields:

After editing fleet.json, run reconcile to generate the agent file and assign the model:

claude-fleet-setup --reconcile

Custom lanes survive updates and profile switches. By default readOnly: true selects read-only tools for a custom lane. An optional tools array overrides the lane's tool list; nested-agent tools are rejected. Built-in reviewers and diagnosis use their role-specific access rules. See Reviewer modes.

Profiles#

Profiles let you switch providers without reinstalling, and you can keep as many as you like: one per gateway, plus native for your Claude login. Lane names stay the same; only the models behind them change.

Switching first saves the current setup, so switching back restores it exactly. Restart Claude Code after switching profiles.

Each profile keeps its own provider policy (the model families it approves and the gateway's naming conventions), lane pins, excluded models, and tier labels. A pin or exclusion you set on one provider does not follow you to another, whose models have different names.

Adding a provider#

agentfleet add saves a new gateway profile without reinstalling:

export OPENROUTER_TOKEN=...   # or leave --token-env out to be prompted
agentfleet add openrouter --gateway-url https://openrouter.ai/api --token-env OPENROUTER_TOKEN
agentfleet use openrouter     # or pass --use to add

It lists the gateway's models first, and saves nothing if the token is rejected or no model is available. Every lane is assigned one of that gateway's models, under a generic policy that approves all of its models. The token is read from the named environment variable, or typed at a hidden prompt when you leave --token-env out; no flag takes the token itself, so it never lands in your shell history. --force replaces a saved profile of the same name. http:// is accepted only for localhost, with --allow-insecure-http.

The gateway must accept Anthropic Messages requests and list its models at /v1/models.

Where profiles are stored#

• Profiles: ~/.claude/agentfleet/profiles/
• Gateway tokens: ~/.claude/agentfleet/secrets/<name>.token (mode 0600, directory mode 0700)

Switching to native#

When you switch to native, AgentFleet removes ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and the ANTHROPIC_DEFAULT_*_MODEL environment overrides from settings, then maps lanes to the opus, sonnet, and haiku aliases.

Gateway profiles set ANTHROPIC_API_KEY to an empty string in settings.json, because Claude Code would otherwise send an API key exported in your shell instead of the gateway token. Switching to native removes it. A non-empty key already in settings.json is yours and is left alone, with a warning.

Commands#

agentfleet#

claude-fleet-setup#

claude-fleet-sync#

claude-agents-doctor#

fleet-setup#

Type /fleet-setup inside Claude Code to run the interactive setup wizard. It audits the fleet, including plugin and MCP health, and offers auto-compact percentage tuning. It then walks through these phases:

1. Phase 1: Silent audit

   Runs claude-fleet-setup --audit --json and agentfleet profiles. Collects: active profile, live model count and tiers, settings health (stale model / advisorModel / ANTHROPIC_*_MODEL values, compaction window), hook health, fleet lane count, and non-fleet agents and skills with their token cost.

2. Phase 2: Status and wizard questions

   Prints a 4–6 line status summary drawn entirely from live audit data, then asks only the questions that apply:

   • Step 1 — Stale settings (only if found): for each stale key, offers up to three live models of the matching tier, plus "Keep unchanged". Applies with claude-fleet-setup --fix-settings.
   • Step 2 — Provider profile: stay on the current profile, switch to a saved one or native, add a provider, or remove one. To add a provider, the wizard asks for a name, the gateway URL, and the name of the environment variable that holds the token, then runs agentfleet add; if you would rather type the token, it gives you the command to run in a separate terminal. It never asks for a token in the chat. Step 3 choices apply to the active profile.
   • Step 3 — Fleet tuning: auto-rank all lanes (recommended), assign models to lanes, fix model tier labels, or keep current assignments.
   • Step 4 — Agent curation (only if non-fleet agents exist): keep all, archive entire domains not relevant to your work (e.g. game_dev, niche_ops), or archive one category. Fleet lanes are never archived.
   • Step 5 — Skills and new agents: archive legacy delegate wrappers, create a custom lane, or do nothing.

3. Phase 3: Apply, verify, summarize

   Runs the chosen commands, then verifies with two required gates:

   1. Gate 1

      claude-fleet-sync --check must pass.

   2. Gate 2

      claude-agents-doctor --check must pass.

   If either gate fails, the wizard shows the error and fixes the cause before finishing. It ends with at most 4 lines summarizing what changed, what was left alone, and whether both gates passed.

Assigning models to lanes#

Choose Assign models to lanes in Step 3 to build the fleet together with the wizard:

1. Suggested fleet

   The wizard reads every live model's description, tier, reasoning support, and context size from your provider's model list, and proposes a model for each lane. It keeps -alt lanes independent and spreads strong models across lanes.

2. Approve or go model by model

   Apply the suggestion as is, or walk through the models one at a time (up to four per question).

3. Pick lanes per model

   For each model the wizard recommends the lanes that fit it best. Pick one or more lanes, Skip it (auto-ranking decides where it helps), or choose Don't use this model to exclude it.

4. Confirm

   Review the resulting fleet, then apply it or start over. The wizard pins only the lanes whose choice differs from auto-ranking, so the rest keep adapting as your provider's models change.

Mods#

Mods are plugins whose code runs inside Claude Code and can draw in its interface. AgentFleet ships a local plugin catalog (marketplace) named agentfleet at ~/.claude/agentfleet/mods/. fleet-status, lane-guard, token-weather, session-info and brain are installed and on by default with mods enabled; fast-jev-compaction is opt-in. See Lane guard for the command guard.

fleet-status#

Version 1.6.0 shows a band above the prompt only when something needs action. Hide dismisses ordinary notices for this session and remembers hidden suggestions. It covers these cases:

• AgentFleet was updated during the session: "Restart Claude Code to use it".
• An automatic update failed: it points to ~/.claude/agentfleet/auto-update.log.
• Fleet lanes have no available model: "Run /fleet-setup".
• Model changes are waiting for review: "Run /fleet-setup".

From 1.6.0 it also warns when a Claude subscription's 5-hour or weekly limit passes 80%, and shows your gateway's budget, limit and exhausted-account warnings. Hiding a usage warning holds until use rises another 5%.

The band also flags failing lanes, which model a lane failed over to, and one unseen project suggestion at a time ("AgentFleet suggests …"). New unanswered options show "New AgentFleet options are available: run agentfleet configure in a terminal." Run /fleet-status for version, profile, "Work style: …", auto-update, model proposals, auto-compact, reviewer access, learning, outages, suggestions, and JEV stats. Its options line says "Options: all reviewed" or "Options: N new (run agentfleet configure)"; from 1.3.0 the count includes the work style and agent-brain options, from 1.5.1 the agent-brain install option, and from 1.6.0 the agent-brain memory question. A missing profile marker shows "not recorded"; auto-update defaults to enabled.

/fleet-tasks opens a closable pane showing session fleet agents, up to eight recent lane reports, and outages. It refreshes every two seconds while open. Close it with Close, the engine close control, or Escape.

The mod reads the install manifest, active marker, auto-update state, model proposals, and AgentFleet's preference, outage, suggestion, lane-report and gateway-usage files. It also uses the engine's project root, agent list and session usage figures. It never reads settings.json, secrets, or saved profiles, and sends nothing anywhere. Command replies are the only additions to model context.

To turn it off:

claude plugin disable fleet-status@agentfleet

token-weather#

token-weather is Anthropic's sample mod (Apache-2.0): a forecast of how full the context window is, drawn above the prompt below the other mods' bands. It is on by default from 2.5.0; an update adds it once and never re-adds it after you remove it. Turn it off with /plugin or agentfleet configure.

session-info#

session-info draws one row above the prompt: the current model and effort, how long this Claude Code has been running, the subagents running now, the git branch, the prompts sent and the session's cost at list price, for example ◆ claude-opus-5.5[1m] · effort high · up 1h 05m · 1 agent running · ⎇ main · 12 prompts · $4.21 at list price. On a narrow terminal it leaves out the last parts first. It reads only what Claude Code already knows and the repository's .git/HEAD; it runs no commands and sends nothing anywhere. The uptime and branch refresh every minute, the rest after each prompt and turn. It is on by default from 2.13.0; an update adds it once and never re-adds it after you remove it. Turn it off with /plugin or agentfleet configure.

brain#

brain adds a /brain command that opens a scrollable pane with agent-brain token usage and, when agent-brain memory is active for the project, the project's memories, critical ones first. ↑/↓ move, Enter shows a memory in full, Esc closes it. With model prices set, it also shows this week's estimated cost for the main conversation and lanes. When your gateway reports its own figures, it shows those instead: this session's cost, the month and the budget left, labelled as reported by your gateway. It is on by default from 2.7.0; an update adds it once and never re-adds it after you remove it. Turn it off with /plugin.

Optional mods#

fast-jev-compaction, by tamaratran (MIT), replaces Claude Code's compaction summary. A fast request to TypeSafe's Jev model decides which old tool calls and results to drop or truncate; everything kept stays word for word. It is not installed by default.

After compaction, a band shows before/after token estimates, percentage reduction, messages kept word-for-word, and elapsed time, or the reason it fell back to Claude's summary. It clears on your next message or with Hide. /jev shows key availability, auto-compact percentage, session totals, and the last five compactions. Lifetime stats in ~/.claude/agentfleet/jev-stats.json contain no conversation content or key. /fleet-status includes a JEV line; agentfleet jev status detects the key in settings env as well as the shell.

claude plugin install fast-jev-compaction@agentfleet

Registration and updates#

On install, when Claude Code 2.1.287 or later is on PATH, the installer runs these commands once. Otherwise it prints them to run by hand and retries on the next update:

claude plugin marketplace add ~/.claude/agentfleet/mods
claude plugin install fleet-status@agentfleet
claude plugin install lane-guard@agentfleet

Updates, including automatic ones, rewrite the mod files in place; the next Claude Code session loads them. The 2.2.0 update adds lane-guard once for installs with mods enabled. After that, disabled or uninstalled mods stay that way.

Opting out#

Pass --no-mods on install or set AGENTFLEET_MODS=0. The choice is remembered, and agentfleet update honors the variable. --mods opts back in. Uninstall removes the agentfleet catalog and its plugins from Claude Code; a rollback to a backup from before 2.1.0 does too.

What gets installed#

Everything lives under your home directory. No root or admin access is required.

Fleet agents#

• ~/.claude/agents/fleet-*.md — one generated agent file per lane, each with an optional fallback model chain (at most three entries, used only for provider unavailability or overload).

Mods#

• ~/.claude/agentfleet/mods/ — the local agentfleet plugin catalog, including ~/.claude/agentfleet/mods/lane-guard/. fleet-status, lane-guard, token-weather, session-info and brain are on by default with mods enabled; fast-jev-compaction is opt-in. See Mods.

Settings#

• ~/.claude/settings.json — merged settings. Unrelated permissions, hooks, plugins, and environment values are preserved. Mode 0600 (may contain a gateway token).

Hooks and scripts#

• ~/.claude/route-to-fleet.py — UserPromptSubmit routing hook.
• ~/.claude/subagent-statusline.py — native subagent status rendering.
• ~/.claude/sync-provider-models.mjs — startup hook for gateway model discovery and fleet reconciliation.
• ~/.claude/sync-model-context.py — PreModelSwitch / PostModelSwitch hook that maintains the global auto-compact percentage and full window, and updates the gateway's real-context cap when needed. Fail-open.
• ~/.claude/provider_catalog.py and ~/.claude/fleet-reconcile.py — provider identity, cache, and reconciliation helpers used by startup hooks.
• ~/.claude/fleet-model-drift.py — fail-open drift detector that writes a mode-0600 proposal and emits bounded startup context.

Activity and suggestions#

• ~/.claude/fleet_watch.py — local lane reports, outage notices, and optional usage counts (on by default for new installs).
• ~/.claude/fleet_suggest.py and ~/.claude/fleet-suggestions.json — local scanner and shipped suggestion catalog.
• ~/.claude/skills/fleet-suggest/SKILL.md — the interactive suggestion wizard.

User-owned preferences and state#

The bundle never manages these files under ~/.claude/agentfleet/: config.json, outages.json, lane-reports.jsonl, main-usage.json, usage/, and suggestions.json. Runtime commands and hooks maintain them; bundle updates do not replace them with shipped defaults.

CLI wrappers#

• ~/.local/bin/agentfleet, claude-fleet-setup, claude-fleet-sync, claude-agents-doctor (POSIX), or equivalent wrappers on Windows.
• ~/.claude/claude-fleet-setup.py — the setup and reconfigure tool. Prompts only when running in a TTY; hooks never invoke it interactively.

Fleet map, policy, and manifest#

• ~/.claude/fleet.json — the canonical fleet map. A legacy mirror is kept in sync at ~/.config/delegate-skills/config.json.
• ~/.config/delegate-skills/provider-policy.json — provider policy. Generic (one catch-all family) on a fresh install; an existing install keeps its provider-specific families and aliases on update, unless --gateway-url names a different gateway. agentfleet use swaps in each profile's own policy.
• ~/.claude/rules/agentfleet.md — the policy for your work style, 600 to 800 words plus about 300 for the ask-first section and 200 for the branch check. Claude Code loads it automatically. AgentFleet manages this file and rewrites it on update. It does not touch your own ~/.claude/CLAUDE.md, so a first install over a personal CLAUDE.md works. Keep your own instructions in CLAUDE.md or in other files under ~/.claude/rules/.
• ~/.claude/.claude-agents-config-manifest.json — installed-tree verification data. The doctor uses this and does not require the source clone.

Preferences#

Run agentfleet configure in a terminal to set every feature in one pass. It asks each question with the current value as the default, grouped under:

• Context: auto-compact percentage, JEV, Context Mode, token-weather.
• Lanes: work style, ask-first, the branch check, reviewer access, lane-guard, the main-session guard.
• Status and reports: the status band, session info, the /brain command, gateway usage, usage learning.
• agent-brain: install it when it is missing, connect it when it is installed, and turn on its memory.
• Updates and checks: automatic updates, then the instruction check.

It ends with what has its own tool: lane models (/fleet-setup), provider profiles (agentfleet use) and model prices (agentfleet config prices). Enter keeps the current value. After an update, the wizard asks only the questions that are new since you last answered. When enabling JEV without an available key, hidden input can save your TypeSafe key as TYPESAFE_API_KEY in ~/.claude/settings.json's env (mode 0600), where commands Claude runs can read it. For private storage, leave the key empty and use /plugin → fast-jev-compaction → Configure.

agentfleet configure --yes              # keep values; mark questions answered
agentfleet configure --preset team.json # apply a preset without prompts
agentfleet configure --export team.json # export settings without secrets

Presets use agentfleet.preset.v1. Feature keys are optional; unknown fields, invalid values, and any other key containing "key", "token", or "secret" are rejected. Example team.json:

{"format":"agentfleet.preset.v1","workStyle":"balanced","compact":70,"jev":true,"reviewerAccess":"full","learn":true,"statusBand":true,"laneGuard":true,"tokenWeather":true,"autoUpdate":true,"agentBrainInstall":true,"agentBrain":true,"agentBrainLocalMemory":true,"askFirst":true}

workStyle and agentBrain are accepted from 2.4.0, askFirst and tokenWeather from 2.5.0, agentBrainInstall from 2.6.0, and agentBrainLocalMemory from 2.10.1. A preset never runs the instruction check.

From 2.10.0 a preset can carry a prices table, which replaces your whole price table; see Usage and estimated cost. Example values, not real rates: "prices":{"codex-luna":{"input":1.25,"output":10}}.

agentfleet config shows every feature. Shared work style, ask-first, branch-check, compact, reviewer, learning, and agent-brain preferences live in ~/.claude/agentfleet/config.json, apply across provider profiles, and survive updates.

agent-brain#

agent-brain is a free tool that records the tokens and cost of each Claude Code session and, from agent-brain 0.5.7, keeps a free project memory on your machine. AgentFleet installs and connects the free tool only; it never asks you to sign in or create an agent-brain account.

• Install: when agent-brain is missing, the wizard offers to install it (default: yes). AgentFleet downloads the release for your system from agentbrain.wecansync.com, checks it against the release manifest's size and SHA-256, and puts the agent-brain executable in ~/.local/bin (on Windows, %LOCALAPPDATA%\Programs\agent-brain). agentfleet config agent-brain on does the same.
• Connect: agent-brain adds its own hooks to Claude Code with agent-brain install --assistant claude-code, using its recommended settings. agentfleet config agent-brain off runs agent-brain uninstall --assistant claude-code.
• Updates: with automatic updates on, AgentFleet checks once a day for a newer agent-brain and installs it in the background, then says so at the next start. It only replaces the copy in agent-brain's standard folder, never a dev build or one a package manager installed, and never moves to an older version.
• Memory: the wizard asks once whether to turn on agent-brain memory (default: no; memory needs a yes, as in agent-brain's own consent prompt). Claude then saves decisions and project context on this machine and reads them back in later sessions; nothing leaves the machine, and Claude takes a short save step now and then, less often when there is nothing to save. A yes runs agent-brain memory enable --yes, first updating the agent-brain AgentFleet installed when it is older than 0.5.7. Existing users are asked on their next interactive update; background updates and --yes never turn it on. agentfleet config agent-brain-memory off runs agent-brain memory disable --all and keeps existing memories. Lanes get the memory search tool only while memory is on; they search memory but leave saving it to the main conversation.
• Memory format: session capture and summaries need agent-brain's current store format (Memory V2). Install, agentfleet doctor and the background agent-brain update upgrade a local store that still uses the older format: they first update the agent-brain AgentFleet installed to 0.5.11 or newer, which copies the store to <store>.pre-v2-<time>.bak next to it before upgrading. A copy installed some other way, or a shared PostgreSQL store, is left alone; agentfleet doctor says what to run. Fresh stores from agent-brain 0.5.11 start in the current format.

Before 2.6.0 AgentFleet wrote agent-brain's hooks itself; an update removes those copies and lets agent-brain write its own.

Instruction check#

Claude Code reads your instruction files every session, so contradictions and stale rules cost tokens and cause odd behavior. agentfleet instructions checks ~/.claude/CLAUDE.md, ~/.claude/rules/, and a project's instruction files. The configuration wizard offers it too.

agentfleet instructions                 # check, then offer edits
agentfleet instructions --project DIR   # include a project's instruction files
agentfleet instructions --check         # report only; edit nothing

The check has two parts:

1. Basic checks

   Lane names that no longer exist, a leftover old AgentFleet policy, duplicated lines, and a total size over 3,000 words.

2. One locked-down Claude Code run

   It has no tools, no hooks, and no MCP servers. It proposes line edits for contradictions, duplicates, and unclear rules.

Each edit is applied only when you say yes, and the file is backed up first in ~/.claude/agentfleet/instruction-backups/. --check reports without editing. Background auto-updates never run the check.

Auto-compact#

One percentage for every model#

compactPercent defaults to 70 in ~/.claude/agentfleet/config.json. Choose an integer from 20 to 95, or off. AgentFleet writes Claude Code's own CLAUDE_AUTOCOMPACT_PCT_OVERRIDE and a 1,000,000-token window (autoCompactWindow and CLAUDE_CODE_AUTO_COMPACT_WINDOW). Claude Code clamps the window to each model and compacts at the chosen percentage of its usable context: the window minus a 20,000-token output reserve.

Switching models keeps the percentage without recalculation, including 30% and other low percentages on smaller models. Gateway profiles also set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the active model's verified real context (capped at 1,000,000 tokens). A model switch asks for a restart only when that gateway cap changes. Native profiles do not need that cap.

Existing 2.2.0 installs migrate automatically. The doctor checks that the percentage in settings matches the preference. off means AgentFleet no longer manages the percentage and removes CLAUDE_AUTOCOMPACT_PCT_OVERRIDE; it does not disable Claude Code's own compaction.

agentfleet config compact 70
claude-fleet-setup --compact-percent 75
# Use an absolute window instead (turns the percentage off):
claude-fleet-setup --compaction 200000

/fleet-setup also offers percentage tuning. --compaction N accepts 100,000–1,000,000 tokens and sets compactPercent to off.

Reviewer modes#

fleet-review, fleet-review-alt, fleet-review-deep, and fleet-security-review have Bash, Edit, and Write by default. Tool access is not permission to edit every review.

• CHECK mode is the default: run tests, linters, builds, and read-only queries to verify findings. Do not edit files or change shared state.
• FIX MODE requires those words in the brief and a list of allowed files. Fix only the listed findings, rerun checks, and report evidence. Another reviewer must review the fix.
• fleet-diagnose-static runs commands to diagnose failures but never edits files.

Set access with agentfleet config reviewer-access full|run|read-only. A lane's tools array in fleet.json can override its tool list; inspect the generated agent's tools before requesting a fix. No lane may spawn nested agents or own outward-facing actions.

Lane guard#

The lane-guard mod is on by default for new installs with mods enabled and is added once on update. It intercepts covered tool calls from fleet subagents. The main conversation is checked only when you turn on the main-session guard.

• Blocks covered git history and working-tree mutations, GitHub writes, package publishing, and deployment commands.
• Blocks covered migrations and destructive SQL in database clients or MCP tools, including DROP, TRUNCATE, and unqualified DELETE or UPDATE.
• Blocks dangerous recursive or forced deletions targeting root, home, parent directories, repository metadata, or a bare wildcard.

Read-only git inspections, tests, builds, linters, SELECT queries, migration status checks, and normal build cleanup remain allowed. A blocked lane must report the command to the main agent instead.

lane-guard also handles model failover: while a lane's own model is down, a new run of that lane starts on the first of its fallback models that works, and the task description ends in (failover: <model>). Turning lane-guard off turns this off too. From lane-guard 1.2.0 it also warns a lane near its turn limit: at 70% of the lane's maxTurns it tells the lane to finish the part it is on, run its check and report, and at 90% to report now. The lane reads the warning after a tool result; you do not see it. For failover it reads ~/.claude/fleet.json, ~/.claude/agentfleet/outages.json and the project's .claude/fleet.local.json, each only as a regular file under 1 MB; it writes nothing.

Main-session guard

From AgentFleet 2.15.0 (lane-guard 1.5.0), agentfleet config main-session-guard on makes lane-guard ask you before the main session, or a subagent that is not a fleet lane, runs a command that discards work or data, or publishes. It is off by default and meant for sessions that skip permission prompts (--dangerously-skip-permissions), where nothing else checks those commands. Commits, pushes, pull requests and branch switches run without a question. lane-guard asks only about:

• git that discards work: a force push or a push that deletes a branch, reset --hard, clean, checking out files over local changes (checkout -- ., checkout HEAD src/app.ts), restore of working-tree files, switch --discard-changes, branch -D and forced branch moves, stash drop|clear, reflog expire, filter-branch/filter-repo;
• GitHub deletes: gh repo delete|archive, gh release delete, gh issue delete, gh api -X DELETE;
• the lane rules for publishing and deployment, migrations, destructive SQL and dangerous rm.

Only Run it runs the command. Don't run it, an answer typed under Other, a dismissed question, or a run with nobody to ask (claude -p) stops it, and Claude is told why. Secrets in the command are masked in the question. Fleet lanes keep their own rules and are never asked.

Outages and lane reports#

On a gateway profile, each lane in ~/.claude/fleet.json has a model and up to three fallback models, ranked from your provider's live models. /fleet-setup can pin a lane to your own list instead, for example fleet-implement on claude-haiku-5.5, then codex-luna, then a Gemini model; the first is the lane's model and the rest are its fallbacks in that order. Native profiles have no fallbacks.

fleet_watch.py watches local subagent activity. When a lane run fails with an API error 429 (quota), 5xx or 529 (overloaded), it records that model as down in ~/.claude/agentfleet/outages.json: for 60 minutes after a 429, 15 minutes after other errors, or until a later run on it succeeds.

• Same-lane failover: with lane-guard on (the default), new runs of the lane start on the first of its fallback models that is not down, and the prompt hook tells Claude to re-dispatch the failed task to the same lane, once; if that run fails too, Claude does the work itself. In the example above, if claude-haiku-5.5 runs out of quota, the next fleet-implement run uses codex-luna, and the Gemini model if codex-luna is down too.
• Another lane: only when every model of a lane is down, or lane-guard is off, does the prompt hook name a lane with a working model instead. In the fleet work style a request routed to that lane is sent to the alternative while the outage lasts.
• Gateway outages: when models from two or more vendors fail within 10 minutes, the gateway itself is failing and switching models will not help. The prompt hook says so once and tells Claude to do the work itself, without dispatching lanes, until the outage expires.
• Status: the fleet-status band shows which model a lane switched to, and /fleet-status lists the models that are down.

Per-lane reports in ~/.claude/agentfleet/lane-reports.jsonl record changed files, forbidden commands, API errors, token counts including cache tokens, the lane's outcome, and whether it was cut off without a report. They are local records, not automatic permission to rerun a blocked command. Use /fleet-status for outages or /fleet-tasks for recent lane activity.

Suggestions#

Run /fleet-suggest in a project to find useful capabilities. The scan is local, makes no network requests, and never reads .env values. The 62-entry catalog covers official-marketplace plugins (including language servers and MCP-server plugins), AgentFleet's optional mods, drafted hooks, a project-skill generator, and /init.

For a repository with a GitHub remote it offers a drafted "Git workflow" section for the project's CLAUDE.md: a branch and pull request per feature, the test command to run first, and no commits, pushes or deploys unless asked. It is written only after you approve the draft. For a new or small project it offers Spec Kit, which writes a spec, a plan and a task list before code; it suits new projects and large features, not small changes.

For a project with an Obsidian vault (a .obsidian/ folder) it offers MCPVault, added read-only and for that project only, so Claude can search the notes without the Obsidian app running. For a large repository (1,000 files or more) it offers Graphify, which maps how files and functions connect and adds a /graphify skill to the project. Both are third-party and installed only after you approve; Graphify needs Python 3.10+ and uv, MCPVault Node.js 20+. Graphify's token-saving figures compare against reading every file whole, so measure it with agentfleet report before keeping it.

The wizard explains each suggestion's access, installs only what you pick, and shows drafted hooks or skills for confirmation before writing. Plugin installation can access the network and runs third-party code with your user permissions. Configure credentials through /plugin or your shell, never in chat.

Learning is on by default for new installs; existing installs keep their setting and are asked once by the configuration wizard. Counters live in ~/.claude/agentfleet/usage/; suggestion state lives in ~/.claude/agentfleet/suggestions.json. The band shows one new suggestion at a time. Opening /fleet-suggest marks suggestions seen and clears it; installed items drop out on the next prompt. Hide remembers the suggestion. When the band is enabled, the model-facing suggestion notice is skipped.

Project lane overrides#

Pin a model for one project without changing global lane assignments:

Overrides live in <project>/.claude/fleet.local.json and generate agents under <project>/.claude/agents/. Claude Code prefers a project agent over a global agent with the same name. These files are project-owned, not managed by bundle updates.

Usage and estimated cost#

Each lane starts its final report with one line: Outcome: done, partial (more remains), blocked (it needs a decision, access or input) or failed. AgentFleet records it. A lane that ended on a tool call without a report, for example at its turn limit, is recorded as cut off. Claude continues a partial or blocked lane with SendMessage, so it keeps what it has read, and stops a lane with TaskStop before redoing its task.

AgentFleet also adds up the main conversation's tokens per model and day in ~/.claude/agentfleet/main-usage.json (kept 35 days), reading Claude Code's transcripts at each prompt, whether or not usage learning is on.

• Per lane and per model: runs, outcomes (done, partial, blocked, failed, cut off, none), API errors, forbidden commands, average tool calls and duration, and tokens.
• Main conversation: tokens per model.
• Estimated cost: only when prices are known.
• Reported by gateway: what your gateway itself reports, when it has a usage endpoint.

Prices come from two places. A gateway that publishes prices in its model list, in OpenRouter's pricing format, is priced automatically. Otherwise, or to override a published price, set your own table, in dollars per million tokens. The numbers below are examples, not real rates:

agentfleet config prices                                  # show the table
agentfleet config prices claude-opus-5.5=5,25,0.5,6.25   # input, output, cache read, cache write
agentfleet config prices codex-luna=1.25,10               # cache prices are optional
agentfleet config prices codex-luna=off                   # remove one model
agentfleet config prices off                              # remove all prices

With prices set, agentfleet report and /brain show an estimated cost, labelled as an estimate. It counts recorded tokens at your prices; it is not a bill, and gateway discounts, batch pricing or subscription plans are not reflected. A model without a price is named and left out of the total, and cache tokens of a model without cache prices are noted as not priced. A gateway can record a model under its own name, for example codex-luna as gpt-6-luna; agentfleet report lists the names it recorded, so price those. Names match ignoring case, a [1m] suffix, and the difference between ., - and _, so a price for claude-opus-5.5 also covers claude-opus-5-5. From 2.11.0 each lane run also records the model it was configured to use and is priced by that name first, so a price for codex-luna covers its runs even when the gateway records them as gpt-6-luna. Your own prices win over published ones, model by model. Token counts come from Claude Code's transcripts, not a provider billing statement.

Reported by your gateway#

Some gateways report spend and limits for the key you use. On a gateway profile, AgentFleet tries three formats once and remembers the one that answers: OmniRoute (/v1/me/status and /v1/me/sessions; the key needs the self:usage scope), OpenRouter (/api/v1/key) and LiteLLM (/key/info). If the gateway answers none of them, it tries again a day later. A gateway that is down, slow or returning server errors doesn't count as an answer: the figures already shown stay, and it tries again after 5 minutes. Claude subscription profiles are skipped.

The prompt hook refreshes the figures in the background, at most every 5 minutes, so prompts never wait on the gateway. They are saved to ~/.claude/agentfleet/provider-usage.json, readable only by you. The key goes only to the profile's own gateway URL, the same one Claude Code sends it to; redirects are refused and responses are size-capped.

• agentfleet report shows a "Reported by gateway" section: the last session the prompt hook checked, today, the week and the month, the budget left, each limit's use, and the number of requests the gateway could not price.
• /brain shows this session's cost as the gateway reports it, labelled as such, instead of the estimate.
• The fleet-status band warns when a budget or limit passes 80%, or when all of a provider's accounts are exhausted, with the reset time.

agentfleet config provider-usage off stops the requests and hides the section. AgentFleet never moves lanes to other models because of these figures; the gateway's own routing and AgentFleet's outage handling cover failures.

Claude subscription: the band warns when the 5-hour or weekly limit passes 80%, using the figures Claude Code gives its status line. Hiding the band holds until use rises another 5%.

Privacy#

On a gateway profile, AgentFleet asks the gateway for the spend and limits of your key (see Reported by your gateway), using the same URL and key Claude Code already sends requests to; agentfleet config provider-usage off stops it. fleet-status sends nothing anywhere; the opt-in fast-jev-compaction mod sends main-conversation text and tool inputs to TypeSafe at each compaction, with tool results replaced by short notes. See Mods for its key requirements and data sharing.

Suggestions scan locally without network access and never read .env values. Usage learning stores command names, tool names, documentation sites, and slash commands per project, never prompt text. Lane reports store observed activity, changed paths, forbidden commands, API errors, outcomes and token counts locally, and main-usage.json stores the main conversation's token counts per model and day, never its text. Use agentfleet suggest --forget to erase usage counters and suggestion history; it does not erase lane reports.

agentfleet instructions sends the text of your instruction files to your model provider through one Claude Code run, as Claude Code already does each session. It runs only when you ask for it or accept it in the wizard.

The routing hook writes only to a mode-0600 JSONL log at ~/.claude/routing-log.jsonl.

What is stored#

Retention and rotation#

• Prompt text excerpts (no-match entries only) are removed after 14 days.
• All entries are removed after 90 days.
• Purging runs at most once per day.
• The log rotates at 2,000,000 bytes.

The hook is fail-open: a logging failure does not block a prompt. The doctor checks these retention and redaction values in both the packaged and installed hook.

The automatic update check makes at most one request a day to https://agentfleet.wecansync.com/releases/latest.json, identified only by the user agent agentfleet/<version>; it sends nothing about your projects, prompts, or provider. Turn it off with agentfleet auto-update off.

Safety#

Upgrading#

To upgrade to the latest release:

agentfleet update

curl -fsSL https://agentfleet.wecansync.com/install.sh | sh

Automatic updates#

From 2.0.4 on, AgentFleet keeps itself up to date. Each time Claude Code starts, a quick hook checks at most once a day whether a newer release exists:

• A newer release with the same major version is installed in the background, with the same checksum verification, backup, and doctor gate as agentfleet update. New sessions use it, and the next session mentions it in one line.
• A new major version is never installed automatically; you get a one-time notice to run agentfleet update.
• The hook never delays startup, prints nothing when there is nothing to report, and is skipped for installs made from a git clone.

agentfleet auto-update status   # enabled?, versions, last result
agentfleet auto-update off      # stop automatic updates
agentfleet auto-update on       # turn them back on

AGENTFLEET_AUTO_UPDATE=0 also turns them off, for example in CI. The state lives in ~/.claude/agentfleet/auto-update.json and each run's output in ~/.claude/agentfleet/auto-update.log. Versions before 2.0.4 need one manual update to get the hook.

Migrating from 1.0.0#

The installer migrates automatically. Lanes that encoded vendor model names in their names are renamed:

Other numbered lanes from 1.0.0 are retired. The old sync-omniroute-models.mjs hook is removed and replaced by sync-provider-models.mjs. The model cache moved to ~/.claude/cache/provider-models-cache.json. The built-in model preferences from 1.0.0 are dropped once during migration. All of this happens inside the same backup/rollback transaction, so the upgrade is reversible.

Moving from CLAUDE.md to the rules file#

AgentFleet 2.3 and earlier kept the policy in ~/.claude/CLAUDE.md. On upgrade, if an earlier install replaced your own CLAUDE.md, AgentFleet restores your original from the backup. An unedited old AgentFleet copy is removed. If you edited it, AgentFleet keeps it and tells you. Run agentfleet instructions to check what is left.

What carries over#

• Per-lane model choices and explicit preferred lists
• Custom lanes defined in fleet.json
• Explicit tier labels
• Saved profiles

Uninstall#

To remove AgentFleet and restore your earlier settings:

agentfleet uninstall

This removes only files and hook entries owned by this bundle. Unrelated top-level settings, plugin selections, and your own rules are left untouched.

Uninstall also removes the agentfleet catalog and its plugins from Claude Code; a rollback to a backup from before 2.1.0 does too.

Rollback#

To restore the state from before the last install or update:

# Use the newest backup:
agentfleet rollback

# Use a specific named backup:
agentfleet rollback --backup ~/.claude/backups/claude-agents-config/20240101-120000

From a source clone you can also run:

python3 bin/install.py --rollback --apply [--backup DIR]

Backups are stored under ~/.claude/backups/claude-agents-config/ in mode-0700 directories and are kept until you remove them manually.

Troubleshooting#

fleet-status doesn't show#

Check claude --version is 2.1.287 or later, and use a supported interface. Run /plugin and look for "1 mod active · fleet-status". If registration was skipped, run these commands by hand:

claude plugin marketplace add ~/.claude/agentfleet/mods
claude plugin install fleet-status@agentfleet

The band only appears when something needs action; /fleet-status always answers.

Auto-compact still uses the old window#

Check agentfleet config. compactPercent: off leaves the window alone. Set agentfleet config compact 70 and restart Claude Code. A model-switch hook writes the next window but cannot change the running session's startup setting.

A lane command was blocked#

Lane-guard returns a rule label for covered destructive or publishing commands. Have the lane report the command and its reason to the main agent; do not ask it to bypass the guard. The main conversation is not blocked; with the main-session guard on, it asks you first. See Lane guard.

Plugin or MCP health warnings#

Run claude-fleet-setup --audit, /fleet-setup, or agentfleet status to inspect the warning. claude-fleet-setup --audit --no-health skips these checks; it does not repair a plugin or MCP server. Configure credentials outside chat.

A lane is marked failing#

With lane-guard on, the lane fails over to its next working model by itself; re-dispatch the failed task to the same lane once. When every model of the lane is down, use the alternative lane the prompt hook names, once. If that fails too, or the hook says the gateway is failing, do the work in the main session. Check /fleet-status or /fleet-tasks for which models are down. An outage lasts 60 minutes after a 429 and 15 minutes after other errors, or ends early when a run on that model succeeds; it never changes the lane's models in fleet.json.

Windows hook path is refused#

Windows hook commands refuse install paths containing $ or a backtick. Use a path without those characters. Version 2.2.0's .cmd shims do not search the current directory for helpers; .ps1 shims carry a UTF-8 BOM for Windows PowerShell.

Checking a Windows machine#

Claude Code runs hooks in Git Bash on Windows. To see whether AgentFleet's and agent-brain's hooks work there, download the check script and run it in PowerShell. It prints versions, agentfleet doctor, agent-brain status, and the result of each AgentFleet and agent-brain hook; it runs no other hooks. agent-brain before 0.5.5 wrote hooks that fail in Git Bash; agent-brain install rewrites them.

irm https://agentfleet.wecansync.com/windows-check.ps1 -OutFile windows-check.ps1
powershell -ExecutionPolicy Bypass -File .\windows-check.ps1

Commands not found after install#

The CLI wrappers are installed to ~/.local/bin/. If your shell does not include that directory in PATH, add it:

export PATH="$HOME/.local/bin:$PATH"

Add this line to your ~/.bashrc, ~/.zshrc, or equivalent to make it permanent.

Node.js not found#

Agent generation and gateway model discovery require Node.js 18 or later. Install it from nodejs.org and ensure node is on your PATH.

Gateway models are not refreshed at startup#

The startup hook reads the gateway URL and token from ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in ~/.claude/settings.json, which the installer and agentfleet use write. It does not read your shell environment. If the gateway is unreachable, the hook uses the cached catalog; if either value is missing from settings.json, it skips discovery and every lane keeps its current model.

To restore the credentials, switch back to a saved gateway profile with agentfleet use <name>, add the gateway again with agentfleet add <name> --gateway-url URL --token-env VAR --use, or re-run the installer with the gateway flags:

# Set the token first, outside shell history.
curl -fsSL https://agentfleet.wecansync.com/install.sh | sh -s -- --provider gateway \
  --gateway-url https://gateway.example.com --gateway-token-env MY_GATEWAY_TOKEN

No approved models after pointing settings.json at another gateway#

Reconcile reports no live approved candidate or unapproved model family: the provider policy still describes the previous gateway's model families, so none of the new gateway's models are approved. This happens when settings.json is edited by hand to point at another gateway. Add the gateway as a profile instead; it gets a policy of its own:

agentfleet add <name> --gateway-url https://gateway.example.com --token-env MY_GATEWAY_TOKEN --use

"another fleet writer is busy"#

The error message another fleet writer (installer or startup hook) is busy; try again in a moment means the installer, a startup hook, or another agentfleet command is holding the write lock. Wait a few seconds and retry. If the lock is stale (the owning process has exited), it will be released automatically.

Doctor: "static lane has write or nested-agent tools"#

A read-only lane's generated agent file contains Bash, Edit, Write, or Agent in its tool list. Re-run reconcile to regenerate the agent correctly:

claude-fleet-setup --reconcile

Doctor: "checksum mismatch"#

An installed file no longer matches its recorded checksum. If you edited the file intentionally, you can re-install to restore it. Otherwise run the full doctor to see all mismatches:

agentfleet doctor

Doctor: generated-agent count mismatch#

The number of agent files in ~/.claude/agents/ does not match the expected count from fleet.json. Run sync to regenerate missing files:

agentfleet sync

Changes not visible after profile switch#

Claude Code reads settings at launch. After switching profiles with agentfleet use, restart Claude Code to apply the new configuration.

agentfleet update fails with HTTP 403#

Versions 2.0.0 and 2.0.1 used the default urllib user agent, which Cloudflare rejected. This was fixed in 2.0.2. Run the install one-liner to update past the broken version:

curl -fsSL https://agentfleet.wecansync.com/install.sh | sh

FAQ#

Development#

Running tests#

python3 -m unittest discover tests

Updating the manifest#

After editing any bundle file, update the manifest. The installer refuses a bundle whose manifest checksums do not match the actual files:

python3 packaging/update-manifest.py

Building a release#

# Build a reproducible release from a git commit:
python3 packaging/build-release.py --ref <commit>
# Produces:
#   dist/releases/<version>/agentfleet-<version>.tar.gz
#   dist/releases/<version>/agentfleet-<version>.zip
#   dist/releases/<version>/SHA256SUMS
#   dist/releases/latest.json

Deploying#

export AGENTFLEET_DEPLOY_HOST=user@server
sh packaging/deploy.sh --dry-run   # list every change and deletion first
sh packaging/deploy.sh             # upload site/, then archives, then latest.json

deploy.sh mirrors site/ with rsync --delete and only syncs into a web root that is empty or already carries the .agentfleet-docroot marker from an earlier deploy. Published release archives are never deleted.

Repository layout#

Contributing and roadmap#

Read CONTRIBUTING.md before opening a pull request: it covers setup, the project rules, tests, versioning, and how to report security issues privately.

The next phase is support for other agent CLIs besides Claude Code: OpenAI Codex CLI, OpenCode, Kilo Code, and Cline. No design is decided yet; open an issue to discuss it before sending code.