Getting started

How it works

Brigade is one binary that can act as a gateway — the long-lived process that holds all state and runs agents — or as a thin client that attaches to it over WebSocket.

            ┌──────────────────────── ~/.brigade/ ────────────────────────┐            │  config · per-agent workspaces · sessions · memory · cron     │            └───────────────────────────────────────────────────────────────┘                                       ▲                                       │ reads/writes (filesystem OR Convex)                     ┌─────────────────┴─────────────────┐  brigade tui ─ws─▶  │           GATEWAY  :7777           │  ◀─ws─ brigade connect  brigade agent      │  per-turn agent loop · routing     │  WhatsApp  ────────▶│  tools · sub-agents · supervisor   │◀──────── cron jobs  MCP client ─stdio─▶│  (brigade mcp → memory server)     │                     └────────────────────────────────────┘

Clients are thin#

The TUI (brigade / brigade tui), brigade connect, and the channel adapters are all WebSocket clients of the gateway. State lives only in the gateway; clients mirror it. Disconnect, walk away, reconnect later — your agents keep running, and so do cron jobs and channel adapters.

The gateway binds to 127.0.0.1:7777 by default — loopback by design. See The gateway for running it headless and installing it as an OS service.

One turn at a time#

Each message runs through a resilient agent loop:

• Resolve the session for the inbound message.
• Assemble the system prompt — persona, eligible skills, and org context.
• Stream the model.
• Run tool calls through approval and ownership guards.
• Persist the transcript, then reply.

The loop is wrapped in resilience: error classification with a retry policy, a content quality (anti-slop) check with a bounded repair retry, smart compaction when context fills, and a model-fallback path if a provider fails mid-turn.

Inbound from anywhere#

A WhatsApp message and a TUI keystroke flow through the same routing pipeline, which resolves each inbound to an (agent, session)pair. A peer on one channel never bleeds into another's context — routing, memory origin scoping, and per-agent isolation all enforce that boundary. See Agents & isolation.

It stays up#

A heartbeat file plus an out-of-process supervisor restart the gateway if its event loop wedges, and per-OS service installers bring it up at login.

$ brigade gateway run         # the long-lived process$ brigade gateway supervise   # out-of-process crash watchdog$ brigade gateway install     # launchd / systemd / Task Scheduler