brigade

Built for enterprise scale. Open for everyone. · An ecosystem, not an app.

🔐 No tokens to juggle. No drama. No copy-pasting secrets, no telemetry — we handle them, not you. Your API keys stay on your own machine, never sent to a middleman.

🔑 No API key? No problem. Sign in with your Claude, ChatGPT, or Copilot subscription — or, if you're already signed into the Claude Code or Codex CLI, reuse that login (no browser, no re-auth).

🩸💥 B³ — Brigade Bloody Benchmark 💥🩸
_{NEW in v1.9.0 · the one command that throws your crew to the wolves (lovingly)}

Three B's. One bloody command. Your crew — loose on the open internet.

Brigade is your crew. Bloody is what you do to it — fling it into the open with no net, down a red-hot tunnel to the wild. Benchmark is the punchline: the only test that ever mattered isn't a lab, it's strangers poking your agents at 3 a.m. Survive that, and you've shipped.

Under the hood it's tame — HTTPS at the edge, no account, no setup. Cloudflare by default, or bring your own relay (bore · frp · sish, all open-source). A secret key rides along invisibly: you never see it, and gate-crashers just bleed out on a 401. Not feeling the name? It also answers to the buttoned-up brigade expose. 🩸

brigade bloody benchmark  ·  brigade expose  ·  brigade expose stop  🩸

Brigade is your personal intelligence, built on enterprise-grade tech: a crew of AI agents on a real org chart that share one long-term memory, Tideline, so what one agent learns, the rest can use. They delegate to each other, switch models mid-task without losing the thread, and act inside the 1,000+ apps you already use. It's an ecosystem you host yourself, with the controls and data sovereignty of enterprise tech: no account to create, no SaaS in the middle.

The same crew runs on a Raspberry Pi or a server. By default it's a small filesystem install; switch to a self-hosted Convex database when you want one. Bring any model: Claude, GPT, Gemini, Llama, or a local Ollama. Privileged actions wait for your approval, and your keys and data never leave your machine. No telemetry.

It's an ecosystem, not an app: one crew you reach from the terminal, WhatsApp, Telegram, Slack, Discord, iMessage, and BlueBubbles, and from your watch, Meta smart glasses, and Meta Quest.

# macOS / Linux — installs Node if needed, then Brigade (no sudo)
curl -fsSL https://brigade.spinabot.com/install.sh | sh
brigade

Start it and you get a fast chat TUI. Keep going and you get isolated agents with their own workspaces and credentials, persistent memory, a skill system, a cron scheduler, sub-agent fan-out, an org hierarchy, messaging channels like WhatsApp and Telegram, 1,000+ app connectors, an MCP memory server, and an optional self-hosted Convex backend — all under one ~/.brigade/ directory you fully own.

One owner, a whole crew — many agents that coordinate through a real org chart, all on hardware and storage you control.

• Why Brigade
• Install
• Quick start
• How it works
• Features
• CLI reference
• In-chat commands
• Built-in tools
• Team Mode
• Multi-agent isolation
• Providers & web search
• Configuration & storage
• Storage modes: filesystem vs. Convex
• MCP memory server
• Tideline (long-term memory)
• Extending Brigade
• Privacy
• Develop from source
• Contributing
• License
• 🦁 Brigadiers

Fastest — handles Node for you (installs Node 22.12+ if you don't have it, then Brigade):

# macOS / Linux
curl -fsSL https://brigade.spinabot.com/install.sh | sh
# …or straight from GitHub:
curl -fsSL https://raw.githubusercontent.com/spinabot/brigade/main/packaging/install/install.sh | sh

# Windows (PowerShell)
irm https://brigade.spinabot.com/install.ps1 | iex
# …or straight from GitHub:
irm https://raw.githubusercontent.com/spinabot/brigade/main/packaging/install/install.ps1 | iex

Already on Node 22.12+? Install straight from npm:

npm i -g @spinabot/brigade

Hitting EACCES / permission denied? Your Node's global folder needs admin rights. Don't sudo — either use the curl … | sh installer above (it sets up a private, user-owned runtime, no root needed), or point npm at a user-writable prefix: npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH.

Then launch onboarding:

brigade

# 1. Set up — pick a provider, paste an API key (or scan local Ollama), choose a model
brigade onboard

# 2. Start the always-on gateway — your crew, channels, and cron jobs live here
brigade gateway run

# 3. Chat with your crew
brigade tui

The onboarding wizard walks you through five steps: (0) storage mode (filesystem or self-hosted Convex), (1) pick a provider (Anthropic, OpenAI, Gemini, OpenRouter, OrcaRouter, Token Market, Ollama, and more), (2) connect it (paste an API key, sign in with a Claude/ChatGPT/Copilot subscription, reuse your Claude Code or Codex CLI login, or connect local Ollama), (3) choose a default model, and (4) web search (pick a search backend; keyless options work out of the box). Subsequent launches resume right where you left off.

brigade tui (or just brigade) auto-starts the gateway if it isn't already running, so for a quick local session you can skip step 2. To keep the gateway alive across reboots, run brigade gateway install (installs a launchd / systemd / Task Scheduler service).

Other handy entry points:

brigade agent -m "summarize ~/today.md"   # one-shot turn, no TUI
brigade connect                            # attach a client to a running gateway
brigade doctor                             # health-check your install

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.

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

• Clients are thin. The TUI (brigade/brigade tui), brigade connect, and 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.
• One turn at a time. Each message runs through a resilient agent loop: resolve the session, assemble the system prompt (persona + skills + org context), stream the model, run tool calls through approval and ownership guards, persist the transcript, reply.
• Inbound from anywhere. A WhatsApp message and a TUI keystroke flow through the same routing pipeline that resolves them to an (agent, session) pair, so a peer on one channel never bleeds into another's context.
• It stays up. A heartbeat file plus an out-of-process supervisor restart the gateway if its event loop wedges; per-OS service installers bring it up at login.

File-backed facts (facts.jsonl) tagged with an origin (owner vs. channel peer) so a peer's facts never leak into your context. Facts decay on three tiers and are deduped at write time, behind a provenance write-gate that stops untrusted sources from overwriting your identity/preferences. The Tideline engine adds hybrid recall (BM25 keyword + model-free vector lane), a typed link graph, and a nightly reflect/consolidate pass. Auto-recall injects only origin-matched facts before each turn. Tools: recall_memory, read_memory, write_memory, manage_memory. → docs/tideline.md

Drop a folder with a SKILL.md into your workspace and Brigade discovers it next turn. Skills are prompt-resident (name + description injected; the model reads the body on demand). Six discovery roots merge in precedence order with eligibility filters for OS, required binaries, env vars, and config. 56 skills ship bundled. Manage with manage_skill.

Delegate work to child agents: spawn_agent (single) and spawn_agents (parallel fan-out). Depth-capped (default 3) and child-count-capped (default 5), with an abort cascade and a completion bridge that wakes the parent when children settle.

Define a crew as a real org chart (cfg.org): members, departments, reporting lines. An A2A (agent-to-agent) policy derives from the graph and governs which agents may message which. Inspect it with brigade org show / explain / doctor, or render a 🦁 Pride chart with the org tool.

A typed channel-adapter contract with a shared inbound pipeline (access control, dedupe, abort triggers, approval routing). WhatsApp (Baileys, QR/code pairing, multi-account, reconnect backoff), Telegram (Bot API token, inline-button approvals, owner bootstrapped on the gateway), Slack (Socket Mode, bot + app tokens, channel/thread chat), Discord (bot token, DM/server/thread chat), iMessage (via the imsg CLI, plain-text only), and BlueBubbles (macOS server, REST-out + webhook-in, reactions/edit/unsend) ship today; the contract is built for more. See Telegram setup for the full walkthrough.

Schedule recurring or one-shot work: cron expressions (with IANA timezones and stagger), fixed intervals, or one-shot timestamps. Payloads can be a system event into your main session, a full agent turn in an isolated session, or a shell script. Jobs survive restarts.

An owner-only composio tool brings 1,000+ app connectors (Gmail, Slack, GitHub, Notion, Calendar, Linear, …) with managed OAuth. Set a key once, then just ask your crew in plain language: "connect my Gmail", "post to #team".

Getting the key: Brigade uses the Composio SDK, so it needs a PLATFORM key (starts with ak_), not the "FOR YOU" consumer key (ck_) that Brigade rejects. At dashboard.composio.dev, set the top-left mode toggle to PLATFORM, open Settings → API Keys, and copy the ak_… key. Hand it to Brigade once ("set my Composio key to ak_…") and it's verified and stored encrypted. Full guide: docs/composio.md.

Send your crew a file and it actually reads it: the analyze_media tool understands PDFs (text or scanned), Word / Excel / PowerPoint (including the images embedded inside them), plain images, audio, and video — auto-selecting the right provider and caching the result. The write side, make_document and edit_document, creates and edits Word / Excel / PowerPoint / PDF in place: fill templates and form fields, set cells and formulas, add charts, and merge / split / stamp / watermark PDFs — all with pure-JS libraries, no sandbox. Drop a document into a channel and Brigade sees it; ask for a report and it hands one back with send_media.

Send your crew an image, a PDF, a screenshot, a video — from the chat TUI, with no ceremony. Four ways in, and they all land as a real attachment:

• Drag a file onto the window — the path turns into a [filename] chip the instant it lands, before you press anything.
• Ctrl+V — paste an image and it attaches; paste text and it types, exactly as before. Brigade reads the clipboard on the paste event your terminal sends, so a copied screenshot just works.
• @path — an autocompleting file picker; type @ and fuzzy-find.
• /attach <path>, /paste, /detach — the explicit backbone, plus /clipboard to see what's on your clipboard and which build is running.

An image on a vision-capable model rides the turn inline — the model actually sees it. A text or source file is read and its contents are inlined directly. PDFs, Office docs, video and audio go through analyze_media (see above). A persistent clipboard worker keeps a paste to a few milliseconds on every platform, and a 📎 attached bar shows what will ride your next message. Works against a local gateway (files travel as paths, so a 400 MB video costs nothing on the wire).

render_video turns an HTML composition into a deterministic MP4 — animated charts and dashboards, data explainers, quote/announcement cards, kinetic typography, branded short-form social clips. Your crew writes a self-contained GSAP-timeline composition (the hyperframes skill teaches the conventions) and Brigade renders it frame-by-frame in an isolated worker (headless Chrome + FFmpeg), then hands back the file with send_media. It's the deterministic, data-driven counterpart to generate_video (generative AI footage). The engine is an optional dependency — the tool stays dormant until you install it with brigade video install, so it adds nothing to a lean setup. (Install it that way, not with a bare npm i: Brigade keeps engine dependencies in its own directory, and npm run from your shell would put it somewhere Brigade never looks.)

Run brigade mcp to expose your long-term memory to any MCP client (Claude Desktop, editors, etc.) as add/search/context tools over stdio, owner-bound.

Brigade is also an MCP server for its own agent. See below.

Already signed into Claude Code? Pick claude-cli as your provider and Brigade drives that binary directly, on your existing subscription. No API key, no per-token bill.

Most tools that wrap a CLI give the model whatever the CLI already had. Brigade does the opposite: it denies the binary's own filesystem, shell, network and sub-agent tools, and serves it Brigade's entire guarded surface — all 30+ native tools plus read/write/edit/bash/grep/ls — over a loopback MCP endpoint scoped to that single turn.

The consequence is the point: every call the binary makes runs through the same objects a normal turn uses. The same ownership gate, the same exec approval prompt, the same path-write and config-write guards, the same memory origin, bound to your real working directory. It cannot reach anything a normal turn could not, because it is holding the same tools. Tool calls appear live in the TUI, land in the session transcript, and are remembered on the next turn.

[mcp/tool-plane] tool-plane connected  agentId=main tools=39
[mcp/tool-plane] tool call  tool=bash  ms=63

The per-turn credential is a 256-bit token, is never logged, and dies with the turn.

Privileged tools use either a per-call ownership gate (cron list is visible to peers; cron add is not) or a blanket owner-only refusal. The bash tool is gated by a per-agent approval allowlist (brigade exec). Secrets in config use ${VAR} references that resolve at read time and are never persisted resolved. Optional AES-256-GCM at-rest encryption in Convex mode (brigade encrypt).

Optional gateway tokens. The gateway is unauthenticated and localhost-only by default — ideal for a single machine. Want more? Add one or more access tokens (brigade gateway token new) and every connection must then present a valid one (Authorization: Bearer, x-brigade-token, or ?token=). Multiple tokens are supported, so you can hand a distinct token to each device and revoke one without disturbing the rest, and the same tokens secure brigade expose. Entirely opt-in: with no tokens configured, nothing changes.

Switch models mid-conversation without losing context. Carrow carries the full transcript onto the new model (it's the same session), re-anchors your thinking level to what the target supports (preserved when it can reason, forced off for a non-reasoning model, bumped for a reasoning-only one), and sanitizes provider-specific reasoning blocks the next provider would reject. It works mid-turn (abort the in-flight run and replay your last message on the new model) or next-turn. This is what makes /model and /provider switches seamless.

A loop-runner drives an agent (or a planner/executor stage) step-by-step under hard guards — token / iteration / time budget, plus no-progress and repetition detection — and stops only when independent done-checks pass or a guard fires, never on the agent's own say-so. Each step's output is gated through the slop detector with a bounded repair retry.

A deterministic, zero-dependency AI-slop detector scans generated text in four passes (vocabulary crutches, cliché phrases, formulaic openers, structural patterns) and flags density, not single words. When output trips the threshold it triggers one bounded repair retry, wired as a post-generation hook — an objective check, not the model grading itself.

Tideline ships a human-gated self-improvement loop: propose changes from telemetry → gate on evaluation → human approve → apply → revert if needed. Brigade also reviews its own behavior and curates/reviews skills from usage. Nothing that affects recall changes without passing the eval bar and a human approval. Throughout, the principle is the same: independent verification, never the agent judging itself.

brigade on its own is shorthand for brigade tui. Run brigade --help or brigade <command> --help for full flags.

Runs Brigade as a WebSocket server with no terminal UI of its own — the long-lived process that channel adapters, cron jobs, and sub-agent spawns all need running.

brigade gateway run --port 7777 --host 127.0.0.1 --verbose
brigade gateway status
brigade gateway stop
brigade gateway restart
brigade gateway install      # install as a system service (launchd / systemd / Task Scheduler)
brigade gateway supervise    # out-of-process crash watchdog

brigade gateway token new        # generate + store an access token (printed once)
brigade gateway token list       # show configured tokens (masked) + whether auth is on
brigade gateway token revoke 1   # remove a token by its number (or its exact value)

Optional authentication. By default the gateway is unauthenticated and refuses to bind anywhere but loopback. To require a token, run brigade gateway token new (repeat for multiple tokens) and restart the gateway. On the same machine, clients read the token from config automatically; elsewhere pass --token <t> or set BRIGADE_GATEWAY_TOKEN. BRIGADE_GATEWAY_TOKENS (comma-separated) adds tokens via the environment. Remove every token to return to open, localhost-only mode.

Attaches a TUI to a running gateway. Same chat experience as brigade, but the agent runs in the gateway process — so you can disconnect, walk away, reconnect later, and pick up where you left off while channel adapters and cron jobs keep running.

brigade connect --host 127.0.0.1 --port 7777

Brigade ships with a default agent called main. Add more — each agent has its own workspace (persona files), auth profiles, exec allowlist, sessions, and optional channel/account routing bindings.

brigade agents                                          # list every agent (default)
brigade agents list [--json] [--bindings]
brigade agents bindings [--agent <id>] [--json]
brigade agents bind --agent <id> --bind <spec> [--bind <spec> …] [--json]
brigade agents unbind --agent <id> (--bind <spec> … | --all) [--json]
brigade agents add [name] [--workspace <dir>] [--model <id>] [--provider <id>]
                  [--agent-dir <dir>] [--bind <spec> …] [--non-interactive] [--json]
brigade agents set-identity --agent <id> [--from-identity]
                  [--name <…>] [--theme <…>] [--emoji <…>] [--avatar <…>] [--json]
brigade agents delete <id> --force [--json]

agents add without --workspace defaults to ~/.brigade/agents/<id>/workspace/. A binding <spec> is "<channel>" or "<channel>:<accountId>". Delete requires --force.

Health-checks Node version, your ~/.brigade/ directory, config, configured providers, log sink, prompt files, and (optionally) a running gateway. Exits 0 on pass, 1 on failure.

brigade doctor
brigade doctor --gateway ws://127.0.0.1:7777
brigade doctor --json            # machine-readable
brigade doctor --strict          # exit 1 on warnings (CI mode)

Bring Brigade up to date and reload the gateway. It auto-detects how Brigade is installed and does the right thing:

• npm global — npm i -g @spinabot/brigade@latest, then restart.
• source checkout — git pull (fast-forward, only when your tree is clean and behind upstream — a dirty tree is left untouched and rebuilt as-is), then npm install, npm run build, then restart.

brigade update            # update + restart the gateway
brigade upgrade           # alias of update
brigade update --check    # report whether newer code is available; change nothing
brigade update --no-restart

If Brigade is installed as a background service (brigade gateway install) the restart is automatic; if you run the gateway in the foreground, restart it yourself to load the new code. Same behavior on macOS, Linux, and Windows.

Read and write the local config without opening the TUI.

brigade config list
brigade config get agents.defaults.provider
brigade config set agents.defaults.provider openrouter
brigade config unset agents.defaults.thinking
brigade config file              # print the resolved config path
brigade config validate          # schema-check the current config

Schedule recurring or one-shot agent turns. Pick exactly one of --cron, --every, or --at; pair --cron with an IANA --tz.

brigade cron list
brigade cron add --cron "0 9 * * *" --tz "Asia/Kolkata" --message "good morning"
brigade cron add --at "2026-06-04T09:00:00+05:30" --message "stand-up reminder"
brigade cron run <jobId>         # fire it now
brigade cron enable <jobId>      # / disable / rm <jobId>

A payload can be a --message (system event into your main session), an isolated agent turn (--model, --tools, --light-context), and an optional delivery target (--channel, --to).

Connect external messaging channels — WhatsApp, Telegram, Slack, Discord, iMessage, and BlueBubbles ship today.

brigade channels list
brigade channels link --channel whatsapp         # WhatsApp: pair via QR / code
brigade channels add  --channel telegram         # Telegram: set up a bot token
brigade channels status --channel telegram
brigade channels allow list --channel telegram   # add / remove allowed senders
brigade pairing approve <code> --channel telegram # approve a waiting sender
brigade channels disable --channel whatsapp

A Telegram bot is a separate account from you, so Brigade establishes ownership on the gateway — never by whoever texts the bot first.

1. Create the bot. In Telegram, message @BotFather, send /newbot, and copy the API token it returns.

2. Add it to Brigade (on the gateway machine), then start the gateway:

   brigade channels add --channel telegram    # paste the bot token when prompted
   brigade gateway restart                     # load the channel

3. Claim ownership. DM your bot anything — it replies with a one-time code and asks an admin to approve it. Approve it once, from the gateway:

   brigade pairing approve <code> --channel telegram

   The first approval on a Telegram bot makes you the owner. Because approving requires access to the gateway machine, that access is the proof it's really you — nobody becomes owner just by sending /start.

4. Run it from the chat. As owner you're never challenged again, and you manage everyone else from Telegram itself:

   Command	Who	What
   /start · /help	admitted	welcome + command list
   /pending	owner	list people waiting for approval
   /approve <code>	owner	admit a waiting person — takes effect immediately, no restart
   /deny <code>	owner	reject a pending request
   /allowlist add|remove <id>	owner	manage approved senders directly
   /whoami · /agent <id>	admitted	see / pin which agent answers you

Everyone else who messages the bot gets a pairing challenge; only you (in chat) or the gateway CLI can let them in. Multiple bots or accounts each track their own owner.

When you're in the chat TUI (brigade or brigade connect):

Keyboard: Enter sends · Ctrl+C stops the current response · Ctrl+D quits · ↑/↓ history · Ctrl+V pastes an image as an attachment · drag a file onto the window to attach it.

Every agent gets a curated toolset. Mutating/privileged tools are owner-gated (either per-call or owner-only).

• Coding (pi SDK): read, write, edit, bash, grep, find, ls
• Memory: recall_memory, read_memory, write_memory, manage_memory
• Sub-agents: spawn_agent (sync), spawn_agents (parallel fan-out)
• Team Mode: team (owner orchestration); leased workers get only coding tools plus the attempt-scoped team_task capability
• Cross-session: sessions_send, sessions_spawn, sessions_list, sessions_history (gated by visibility + A2A policy)
• Crew management: agents_list, manage_agent, manage_skill, manage_provider, manage_access, manage_channel_access, org (when cfg.org is set)
• Scheduling: cron (schedule jobs from inside a turn)
• Web: web_search, fetch_url, browser (when a provider is configured)
• Connectors: composio (1,000+ apps), oauth_authorize
• Generation: generate_image, generate_video, generate_speech, generate_music, render_video (HTML→MP4 motion graphics, optional engine)
• Documents & media: analyze_media (read/understand PDF · Office · image · audio · video), make_document · edit_document (create & edit Word/Excel/PowerPoint/PDF)
• Channels: send_message, send_media (when a channel is linked)

Team Mode adds durable rooms and multi-agent task graphs on top of Brigade's existing agent loop. It supports dependency joins (all, any, quorum), retries, leases and fencing, cancellation and timeouts, run budgets, approvals, handoffs, artifacts, restart recovery, and a room-scoped streaming protocol for UIs. A room is a durable group/channel: its public conversation supports threads, replies, explicit agent mentions, attachment references, search, reactions, pins, edits, soft deletion, reconnect history, and authoritative metrics. Mentions communicate but never silently launch work; delegation, consultation, and ownership handoff remain explicit operations. Worker attempts have isolated transcripts, results return durably to the room coordinator, and the owner can launch a validated graph with one team.delegate call. The same tool can update configured room membership or archive an idle room without bypassing the store's membership and active-run guards. It works in both default filesystem mode and optional Convex mode; it does not require Tideline or a SaaS control plane. The current Convex collaboration adapter is a single-owner Phase-1 scale profile whose retained core state must stay below its documented 16 MiB hydration boundary; filesystem mode does not have that Convex transaction limit.

See docs/team-mode.md for the execution model, agent tools, storage guarantees, and versioned WebSocket API. Brigade ships Team Mode as a headless backend so products can build their own web, desktop, or mobile room experience without coupling UI code to the runtime package.

Every agent has its own workspace, persona, credentials, memory, sessions, exec approvals, and routing bindings. By design:

• Agent A cannot read agent B's session transcripts (unless visibility ≠ self).
• Agent A cannot send to agent B's session unless cfg.session.agentToAgent (the A2A policy) permits it.
• Memory facts are per-agent and origin-scoped — they don't bleed between agents.
• Provider credentials are per-agent — e.g. support and prod-bot can use different accounts.

The default policy is visibility: "self" (an agent only sees its own sessions); switch to "tree" to let a parent see sub-agents it spawned.

Models out of the box: Anthropic, OpenAI, Google Gemini, OpenRouter, OrcaRouter, Token Market, Groq, Cerebras, xAI, DeepSeek, Mistral, Ollama (local), and Custom OpenAI-compatible endpoints (Together, Fireworks, vLLM, LM Studio, on-prem gateways — anything that speaks /v1/chat/completions). Connect several at once, switch with /model, and Brigade keeps your context across the switch.

Sign in with a subscription — no API key. Don't want to manage keys, consoles, and billing? Use the subscription you already pay for. Two ways, both keyless:

• Browser sign-in — brigade login signs in to Claude Pro/Max, ChatGPT Plus/Pro, or GitHub Copilot over OAuth (also offered inside brigade onboard).
• Reuse a CLI login — already signed into the Claude Code or Codex CLI on this machine? brigade onboard offers "Reuse this machine's login" — one keystroke, no browser, no re-auth.

Keys still work if you prefer them; either way the credential is sealed on your own machine (auto-refreshed when the provider supports it).

The claude-cli provider goes one step further: it runs the claude binary as Brigade's engine, with the binary's own tools denied and Brigade's guarded toolset served back to it over a per-turn loopback MCP endpoint. Your crew, your memory, your approval prompts — on a subscription, at no marginal token cost. See Subscription backends.

Web search is pluggable and auto-selected by what you've configured: Tavily, Brave, Exa, Perplexity, Firecrawl, SearXNG (keyed) and DuckDuckGo, Wikipedia, Hacker News, arXiv, GitHub, npm, local Ollama (keyless).

Brigade keeps every byte of state under ~/.brigade/ — rm -rf ~/.brigade truly wipes everything it knows.

~/.brigade/
├── brigade.json              # main config (JSON5; ${VAR} secret refs preserved on write)
├── brigade.json.bak{,.1..4}  # rotating forensic backups (mode 0600)
├── models.json               # custom provider catalog (Ollama / custom endpoints)
├── workspace/                # default agent (main): SOUL/IDENTITY/AGENTS/USER/TOOLS/
│   │                         #   BOOTSTRAP/HEARTBEAT.md persona files
│   ├── memory/facts.jsonl    # write_memory / recall_memory
│   └── skills/               # drop-a-folder skills
├── agents/<id>/              # per-agent isolation
│   ├── workspace/            # same shape, per agent
│   ├── sessions/<id>.jsonl   # transcripts (one file per session)
│   └── agent/                # auth-profiles.json, models.json (mode 0600)
├── channels/<id>/<account>/  # channel state (auth, allow-from, pairings)
├── cron/runs/<jobId>.jsonl   # cron state + per-run logs
├── logs/                     # daily rolling logs + config audit
└── gateway.{pid,lock,heartbeat}

Useful environment overrides:

Brigade defaults to filesystem mode (everything under ~/.brigade/). It also ships an optional Convex backend you can run fully self-hosted — no cloud account, no telemetry. The mode resolves from a sticky sentinel and freezes once at boot.

brigade store mode show                                   # what mode am I in?
brigade store mode set convex --convex-url http://127.0.0.1:3210
brigade store migrate --to convex --dry-run               # preview a migration
brigade store migrate --to filesystem                     # copy data back

Run the bundled self-hosted Convex backend — no Convex account, no separate install. The backend binary + functions ship inside Brigade, so this works from anywhere once brigade is installed, not just a repo checkout:

brigade convex dev       # download the backend if needed, then run it + dashboard (foreground)
brigade convex status    # is the backend up? (probes :3210)
brigade convex push      # deploy the bundled Convex functions to the backend
brigade convex codegen   # regenerate convex/_generated/ against the local backend

brigade convex dev runs the backend on :3210, the site proxy on :3211, and the dashboard on :6791, with binaries + data under ~/.brigade/convex/. Ctrl-C to stop; the brigade convex:dev colon form works too. Then point Brigade at it with brigade store mode set convex --convex-url http://127.0.0.1:3210 (above).

Running from a repo checkout? The npm run convex:install / convex:dev / convex:codegen scripts still work and write into the repo's bin/ + .convex-data/.

Turn on at-rest encryption for Convex byte columns (credentials, persona, memory, cron payloads, transcripts) with BRIGADE_ENCRYPTION_KEY:

brigade encrypt init     # generate a 32-byte key
brigade encrypt status   # is a key configured? self-check
brigade encrypt test     # round-trip seal/open

See docs/convex-mode.md for the full runbook.

Brigade can expose your long-term memory to any MCP client over stdio:

brigade mcp                 # serves the `main` agent's memory
brigade mcp --agent support # a specific agent

It surfaces add / search / context tools, owner-bound. Point an MCP client (an editor, a desktop assistant, etc.) at the command brigade mcp.

Tideline is the model-agnostic long-term memory engine that backs Brigade. Where a transcript is what an agent just said, Tideline is what it knows — durable facts about you and your work, written under a trust gate, recalled by meaning, decayed when stale, and reconciled over time. It's structured to be lifted out as its own package (brigade-tideline).

It's built to survive the three ways naive "vector store" memory breaks:

The flow, end to end:

WRITE    add() → write-gate (trusted vs untrusted × protected segment) → dedup → store
RECALL   query → BM25 + HRR vector → graph walk → decay×trust score → origin filter → budgeted block
MAINTAIN decay GC → nightly dream (consolidate/relate) → contradiction detection

Each record carries a segment (identity / preference / correction / relationship / project / knowledge / context), a tier (short / long / permanent), an importance, and an origin.

import { Tideline } from "brigade-tideline";

const memory = Tideline.open("/path/to/workspace");
memory.add({ content: "I keep a strict vegetarian diet.", segment: "preference" });
const block = memory.context("dietary restrictions", { maxChars: 800 });

In Brigade you reach it through the recall_memory / read_memory / write_memory / manage_memory tools and via auto-recall (which fails closed for unknown peers, so operator memory never leaks). An evaluation harness (brigade-tideline/eval) measures recall@k / MRR / nDCG@k on deterministic gold sets — run npm run bench.

📖 Full write-up: docs/tideline.md · package surface: src/tideline/

Brigade ships a typed extension SDK. Drop a module into ~/.brigade/extensions/ and register against a slot:

import { defineModule } from "@spinabot/brigade/extension-sdk";

export default defineModule((b) => {
  b.tool({ /* a custom agent tool */ });
  b.webSearch({ /* a search provider */ });
  b.channel({ /* a messaging adapter */ });
  b.gatewayMethod({ /* a gateway RPC */ });
});

Shipped slots include tool, hook, command, modelProvider, channel, webSearch, webFetch, integration, service, httpRoute, and gatewayMethod. Voice/media slots (tts, stt, mediaGen) and pluggable memory backends have locked contracts with implementations on the roadmap. See AGENTS.md for how to add a tool, channel, skill, or provider.

Brigade is a local CLI. Your API keys never leave your computer; they're stored in your home directory at mode 0600 and used only to talk to the providers you connect. No telemetry, no analytics, no cloud component. For Ollama and custom endpoints, requests stay on your network. The gateway binds to 127.0.0.1 by default.

git clone https://github.com/spinabot/brigade.git
cd brigade
npm install
npm run build        # tsc → dist/

Run from your checkout (npm scripts wrap the binary so you don't type node):

npm run dev          # smart runner: rebuilds dist/ if src/ is newer, then runs
npm run dev:tsx      # run TypeScript directly via tsx (no build, slower per call)
npm run watch        # tsx --watch: auto-restart on edit
npm link             # make `brigade` available globally → this checkout

Surface shortcuts (all wrap scripts/run-brigade.mjs):

npm run onboard          # brigade onboard
npm run tui              # brigade tui
npm run gateway          # brigade gateway run     (also gateway:status / gateway:stop)
npm run connect          # brigade connect
npm run agent -- -m hi   # brigade agent -m hi
npm run agents:list      # brigade agents list     (agents:add / agents:bind / …)
npm run status           # brigade status          (status:json)
npm run doctor           # brigade doctor          (doctor:json / doctor:strict)
npm run channels:list    # brigade channels list   (wa:link / pairing:list / …)
npm run skills:list      # brigade skills list
npm run logs             # brigade logs            (logs:follow)

Checks (CI runs the same three):

npm run typecheck    # tsc --noEmit, strict
npm test             # node:test, tempdir-isolated (281 test files)
npm run build        # ensure the production build compiles
npm run bench        # memory / recall evaluation benchmarks

Storage / Convex dev: npm run store:mode:show, npm run convex:install, npm run convex:dev, npm run convex:codegen.

Full contributor guide, repo layout, and conventions live in AGENTS.md.

Contributions are welcome! Read CONTRIBUTING.md for dev setup, coding conventions, and the Conventional-Commits release flow. For security issues, see SECURITY.md — please report privately. Releases are automated with release-please; see docs/RELEASING.md.

Questions or ideas? Open a discussion or email [email protected] (security → [email protected]).

MIT © Spinabot

A pride of contributors who make Brigade better. Thank you to everyone who has joined the crew!

Want to join the pride? See CONTRIBUTING.md.