CAFleet

A message broker and agent registry for coding agents — a Claude Code plugin plus a local broker CLI.

CAFleet is a local-only tool. It runs on a single developer machine without authentication. Do not expose the broker on a shared network unless you accept that every listener can see and act within every session.

Install

Install the plugin in Claude Code

/plugin marketplace add himkt/cafleet
/plugin install cafleet@himkt-cafleet

This adds 11 plugin-packaged skills under the cafleet namespace: /cafleet:cafleet, /cafleet:agent-team-monitoring, /cafleet:agent-team-supervision, /cafleet:design-doc, /cafleet:design-doc-create, /cafleet:design-doc-execute, /cafleet:design-doc-interview, /cafleet:create-figure, /cafleet:my-slidev, /cafleet:research-presentation, /cafleet:research-report. Run /help in Claude Code to see them.

Install the plugin in Codex

codex plugin marketplace add himkt/cafleet

Then complete the in-UI install when prompted by codex. The same 11 plugin-packaged skills (cafleet, agent-team-monitoring, agent-team-supervision, design-doc, design-doc-create, design-doc-execute, design-doc-interview, create-figure, my-slidev, research-presentation, research-report) land in Codex from the shared skills/ tree.

Install the broker CLI (required for the plugin to function)

uv tool install cafleet     # or: pip install cafleet
cafleet db init             # apply schema migrations (idempotent; rerun after upgrades)

The default database is ~/.local/share/cafleet/registry.db. Override with CAFLEET_DATABASE_URL (use an absolute path — SQLAlchemy does not expand ~ in SQLite URLs).

Try it

In any tmux session, paste this into Claude Code:

/cafleet:design-doc-create I want to create a simple TUI calculator

Codex:

$cafleet:design-doc-create I want to create a simple TUI calculator

Claude (the Director) bootstraps a CAFleet session, spawns a Drafter and a Reviewer in adjacent tmux panes, drives the clarification → draft → review loop through the message broker, and lands a polished design doc at design-docs/my-feature/design-doc.md.

Want more? See skills/cafleet/SKILL.md for the raw broker primitives and skills/design-doc-create/SKILL.md for the orchestration this example uses.

CLI cheatsheet

CLI reference (per-command sections for session, member, doctor, server; agent / message / db init covered via the option-source table and cafleet <cmd> --help): docs/spec/cli-options.md. Message envelope shape (compact rendered + --full typed-column): docs/spec/message-envelope.md.

Notable flags

Coding agents

cafleet supports two coding-agent binaries for member panes: claude (Claude Code) and codex (OpenAI Codex CLI). Pass --coding-agent {claude,codex} on cafleet session create (operator-declared metadata for the root Director) and cafleet member create (selects the spawn-command builder and records the placement). The default is claude, so existing invocations are unchanged. A single Director may spawn both claude and codex members in the same session. Operational details for codex members — including the codex CLI version pin and verification recipe — live in docs/codex-members.md.

[!IMPORTANT]
Codex members need the cafleet DB directory to be writable from inside the codex sandbox. Add it to sandbox_workspace_write.writable_roots in any config.toml codex reads (e.g. ~/.codex/config.toml):

[sandbox_workspace_write]
writable_roots = ["/home/<you>/.local/share/cafleet"]

Use the absolute path matching CAFLEET_DATABASE_URL or the default XDG location.

Message body truncation

cafleet message {send,poll,ack,cancel,show} truncate the message text body to the first CAFLEET_MAX_TEXT_LEN Unicode codepoints (default 200) plus a single … codepoint suffix in both text and --json output by default. This collapses per-poll token cost for inbox-polling agents whose bodies typically run several hundred characters. Pass --full (per-subcommand option, placed after the subcommand name) to restore the un-truncated body and the full typed-column envelope. Empty bodies and bodies whose codepoint length is at most CAFLEET_MAX_TEXT_LEN pass through unchanged with no marker. cafleet message broadcast is different — it returns a broadcast_summary task whose text is a generated summary string (e.g. Broadcast sent to N recipients), not the original body, so its summary always emits in full. The --full flag is preserved on message broadcast for surface consistency but is a no-op. The /ui/api/* WebUI responses are not truncated. See docs/spec/cli-options.md § Message Body Truncation and docs/spec/message-envelope.md for the full rendering rules.

Architecture

CAFleet ships a unified cafleet CLI and an admin WebUI on top of a single-file SQLite database. Sessions partition agents into isolated namespaces; the CLI accesses SQLite directly through a shared broker module, so no HTTP server is required for agent operations. See ARCHITECTURE.md for the full design.

Project structure

Development

Clone the repo and use mise for all common tasks:

git clone https://github.com/himkt/cafleet.git
cd cafleet

mise //:uv-sync
mise //cafleet:install    # editable uv tool install of the cafleet CLI
cafleet db init           # apply schema migrations (idempotent; rerun after upgrades)

mise //cafleet:lint       # ruff check + ruff format --check
mise //cafleet:format     # ruff format
mise //cafleet:typecheck  # ty
mise //cafleet:test       # pytest

mise //admin:build        # build the WebUI (required before /ui/ is served)
mise //admin:dev          # WebUI dev server (Vite)

License

MIT