Fleet docs v0.2.0-rc.448

Bots

A bot is a named agent that lasts (#598, spec-agents §7). It has:

  • An identity: a name, a handle @<your login>-<name>, an avatar and a one-line purpose.
  • A config layer: its own CLAUDE.md, rules, skills, subagents, commands, MCP servers and settings. In a bot's turn this layer goes on top of the fleet layer and yours; the most specific wins (spec-agents §4.2).
  • A memory dir: the files Claude Code keeps in its auto-memory dir. Fleet lays them into each of the bot's turns and reads them back when the turn ends, so the bot remembers between turns on any node. Claude Code keys that dir by the repo's main checkout, so every worktree of a repo shares it; fleet lays the memory there.
  • A model: its agents run on it unless the spawn names another.

Your bots are yours: no other person sees or changes them, an admin included. A fleet bot (handle @fleet-<name>) is shared: every person can run it, and only an admin changes it.

Make one and run it

fleet bot new ops --purpose "Watches CI and the nodes" --avatar 🛠 --model sonnet
mkdir -p ~/bots/ops && $EDITOR ~/bots/ops/CLAUDE.md     # its persona and job
fleet home push --bot ops ~/bots/ops                     # its layer
fleet spawn ci-check --bot ops --project swarm-lab < brief.md

The page Bots (/bots) lists your bots and the fleet's. New chat starts a chat as the bot. Memory shows and edits its memory files; Reset clears them after it copies them to an archive. Edit changes the whole bot (below).

Change a bot

Edit on a bot's card opens it in the form (#654): the avatar, purpose and model, its Instructions (CLAUDE.md), its Action rules, its Skills and any other file of its layer. Each action rule is not set (the fleet's and your layer decide; act when none does), act, preapproved (with standing approvals: patterns such as swarm-lab/*), ask or handoff. Under each rule the page says what its turns run with now, merged from the fleet, you and the bot, and marks a rule that differs until you save. Changes to save shows the diff against its layer. Save writes the layer as one new version; if someone saved in between, it refuses and you open it again. Its next turn runs with the new version. Routines are changed in the routine table.

You can also ask the bot (or any chat of yours) to change it: "set Change config to act". The chat calls bot_draft with the bot's name, which drafts a revision: only what changes, checked against the bot's layer. You get an inbox proposal that names each change ("Change config (change-config): handoff → act") and carries it; Approve writes it. Its link, /bots?draft=<chat>, opens the same revision in the form with the diff: Save (approve) approves the item, with your edit if you made one. A newer draft from the chat closes the older item. The chat never writes the layer itself.

Make one on the page

The New bot card has two tabs (#630):

  • Fill it in: the whole bot in one form. The name, avatar, purpose and model; its Instructions (the layer's CLAUDE.md); its Routines (0 or more, the same fields as the routine form); its Action rules (for each of the six built-in kinds: act, ask or handoff; only the ones that are not act are written to actions.json); and its Skills (a name and a SKILL.md each). Create makes the bot, saves its layer, then makes each routine. When a part fails after the bot exists, the page says which part and keeps the bot; fix that part on the page (the layer with fleet home push --bot, the routine with the routine form).
  • Interview with Claude: starts a chat that runs the bot-builder skill. Claude asks one question at a time: the job and who it serves, when it runs, which project, what done looks like, what it may do alone, what it needs, the budget, and a name. It pushes back on a vague purpose, a schedule with no budget and a write action with no approval rule. Then it posts a draft. The page checks for a draft every 3 seconds, fills the form, opens Fill it in and shows "Drafted by Claude: review, then Create", with Claude's notes (a login, a repo). A Secrets this bot needs card lists what the bot reads, each set or missing. Create does not wait for it. Paste a value once (never shown again), attach a value fleet already holds (your own, another project's, the cos store), or add the repo as a project, all on the page. A secret marked file reaches the run as a 0600 file, its env var naming the path (a Google service account key). Ask Claude for a change and it posts a new draft; if you typed in the form since the last one, the page asks before it replaces your edits.

Claude drafts; you create. The chat cannot make a bot: only a person's own call does. A draft is kept on the server for 24 hours after its last change, in memory: after a server restart, ask the chat to post it again. Only you see your chats' drafts.

fleet serve puts the skill in the fleet layer at skills/bot-builder/SKILL.md when that file is not there. An admin may edit it (Admin, Config); a restart does not overwrite the edit. Delete the file to get the built-in version back on the next restart.

The summary card

Each bot's card says what it does (its purpose), where it runs (the projects of its routines, and its model), how often (each routine in words, with the next run), what it does alone, does only if pre-approved, asks you first or leaves to you, and what it spent in the last 24 hours against the sum of its routines' budgets. The action rules are the ones its next turn runs with: the fleet's, yours and the bot's layers merged, and the card names the layer versions they came from.

Commands

Command What it does
fleet bot ls Your bots and the fleet's
fleet bot new <name> [--purpose P] [--avatar A] [--model M] [--shared] Make a bot; --shared makes a fleet bot (admins)
fleet bot show <bot> / set <bot> --purpose ... / rm <bot> Read, change, remove. rm refuses while an agent runs as the bot
fleet bot memory ls|pull|push|reset <bot> [dir] Its memory dir
fleet home push|pull|versions|use --bot <bot> Its config layer, with versions and rollback like your own
fleet home ls --layer effective --bot <bot> What a turn of the bot gets: fleet, you and the bot, merged
fleet spawn <name> --bot <bot> Run an agent as the bot

API: PUT /v1/bots/draft (a chat's token; the bot_draft MCP tool) and GET /v1/bots/draft?conversation=<chat id> (the chat's person) carry a draft. A draft is {bot, instructions, files, routines, notes}; a bad one is a 400 that names the problem. A draft that names a bot you have is a revision: the server adds revises, base, changes and item (the inbox proposal).

<bot> is the bot's name, its handle or its id. A name finds your bot first, then the fleet's.

Limits

  • Memory is at most 8 MiB and 2000 files. A turn that leaves more keeps the memory it had.
  • Two agents of one bot that run at once each write the memory back when their turn ends; the last one wins.
  • Memory and the layer are laid only for Claude turns. A Codex turn of a bot gets neither yet.
  • A revision's inbox item holds at most 20000 characters. A bigger one is posted as info with the link: save it on the page.
  • A draft lives 24 hours, in memory. Its inbox proposal stays after that, and approving it works.

Routines (work the bot starts by itself on a schedule or an event) are in Routines.