![\"Brigade](\"https://raw.githubusercontent.com/spinabot/brigade/main/assets/brigade-banner-on-black.gif\")
\n \n \n
\n Built for enterprise scale. Open for everyone. · An ecosystem, not an app.\n
\n\n\n 🔐 No tokens to juggle. No drama. No copy-pasting secrets, no telemetry —\n we handle them, not you. Your API keys stay on your own machine, never sent to a middleman.\n
\n\n\n 🔑 No API key? No problem. Sign in with your Claude, ChatGPT, or\n Copilot subscription — or, if you're already signed into the Claude Code or\n Codex CLI, reuse that login (no browser, no re-auth).\n
\n\n\n 🩸💥 B³ — Brigade Bloody Benchmark 💥🩸
\n NEW in v1.9.0 · the one command that throws your crew to the wolves (lovingly)\n
\n Three B's. One bloody command. Your crew — loose on the open internet.\n
\n\n\n 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.\n
\n\n\n 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. 🩸\n
\n brigade bloody benchmark · brigade expose · brigade expose stop 🩸\n
\n \n
\n ![\"CI](\"https://img.shields.io/github/actions/workflow/status/spinabot/brigade/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI\")
![\"npm](\"https://img.shields.io/npm/v/@spinabot/brigade?style=for-the-badge&logo=npm&logoColor=white&color=CB3837\")
\n
![\"node](\"https://img.shields.io/node/v/@spinabot/brigade?style=for-the-badge&logo=nodedotjs&logoColor=white&color=5FA04E&label=node\")
![\"MIT](\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\"){kind=icon}
\n ![\"website\"](\"https://img.shields.io/badge/website-brigade.spinabot.com-E8B021?style=for-the-badge&logo=googlechrome&logoColor=white\"){kind=icon}
--channel telegram # approve a waiting sender\nbrigade channels disable --channel whatsapp\n```\n\n### Telegram setup (end to end)\n\nA Telegram bot is a separate account from you, so Brigade establishes ownership on\nthe **gateway** — never by whoever texts the bot first.\n\n1. **Create the bot.** In Telegram, message [@BotFather](https://t.me/BotFather),\n send `/newbot`, and copy the API token it returns.\n2. **Add it to Brigade** (on the gateway machine), then start the gateway:\n ```bash\n brigade channels add --channel telegram # paste the bot token when prompted\n brigade gateway restart # load the channel\n ```\n3. **Claim ownership.** DM your bot anything — it replies with a one-time code and\n asks an admin to approve it. Approve it once, from the gateway:\n ```bash\n brigade pairing approve --channel telegram\n ```\n The **first** approval on a Telegram bot makes you the owner. Because approving\n requires access to the gateway machine, that access *is* the proof it's really\n you — nobody becomes owner just by sending `/start`.\n4. **Run it from the chat.** As owner you're never challenged again, and you manage\n everyone else from Telegram itself:\n\n | Command | Who | What |\n |---|---|---|\n | `/start` · `/help` | admitted | welcome + command list |\n | `/pending` | owner | list people waiting for approval |\n | `/approve ` | owner | admit a waiting person — takes effect immediately, no restart |\n | `/deny ` | owner | reject a pending request |\n | `/allowlist add\\|remove ` | owner | manage approved senders directly |\n | `/whoami` · `/agent ` | admitted | see / pin which agent answers you |\n\nEveryone else who messages the bot gets a pairing challenge; only you (in chat) or\nthe gateway CLI can let them in. Multiple bots or accounts each track their own owner.\n\n---\n\n## In-chat commands\n\nWhen you're in the chat TUI (`brigade` or `brigade connect`):\n\n| Command | What it does |\n|---|---|\n| `/agent []` | Show or switch the agent this connection is bound to |\n| `/agents` | List every agent the gateway knows about |\n| `/sessions`, `/session ` | List or switch sessions for the current agent |\n| `/model []`, `/provider` | Switch model (picker or by id), or add a provider mid-session |\n| `/thinking ` | Reasoning effort (off, minimal, low, medium, high) |\n| `/reasoning [on\\|off]` | Toggle whether thinking blocks render |\n| `/compact` | Force a context compaction now |\n| `/abort`, `/steer \"\"` | Stop the current turn, or inject mid-turn guidance |\n| `/attach `, `/paste`, `/detach [\\|all]` | Stage a file, pull from the clipboard, or unstage |\n| `/clipboard` | What's on your clipboard, plus the running build + worker health |\n| `/usage` | Token + cost usage for this session |\n| `/help`, `/exit` | Show all commands / quit |\n\nKeyboard: **Enter** sends · **Ctrl+C** stops the current response · **Ctrl+D**\nquits · **↑/↓** history · **Ctrl+V** pastes an image as an attachment · drag a\nfile onto the window to attach it.\n\n---\n\n## Built-in tools\n\nEvery agent gets a curated toolset. Mutating/privileged tools are owner-gated\n(either per-call or owner-only).\n\n- **Coding (pi SDK):** `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`\n- **Memory:** `recall_memory`, `read_memory`, `write_memory`, `manage_memory`\n- **Sub-agents:** `spawn_agent` (sync), `spawn_agents` (parallel fan-out)\n- **Team Mode:** `team` (owner orchestration); leased workers get only coding\n tools plus the attempt-scoped `team_task` capability\n- **Cross-session:** `sessions_send`, `sessions_spawn`, `sessions_list`,\n `sessions_history` (gated by visibility + A2A policy)\n- **Crew management:** `agents_list`, `manage_agent`, `manage_skill`,\n `manage_provider`, `manage_access`, `manage_channel_access`, `org` (when\n `cfg.org` is set)\n- **Scheduling:** `cron` (schedule jobs from inside a turn)\n- **Web:** `web_search`, `fetch_url`, `browser` (when a provider is configured)\n- **Connectors:** `composio` (1,000+ apps), `oauth_authorize`\n- **Generation:** `generate_image`, `generate_video`, `generate_speech`, `generate_music`, `render_video` (HTML→MP4 motion graphics, optional engine)\n- **Documents & media:** `analyze_media` (read/understand PDF · Office · image · audio · video), `make_document` · `edit_document` (create & edit Word/Excel/PowerPoint/PDF)\n- **Channels:** `send_message`, `send_media` (when a channel is linked)\n\n---\n\n## Team Mode\n\nTeam Mode adds durable rooms and multi-agent task graphs on top of Brigade's\nexisting agent loop. It supports dependency joins (`all`, `any`, quorum),\nretries, leases and fencing, cancellation and timeouts, run budgets, approvals,\nhandoffs, artifacts, restart recovery, and a room-scoped streaming protocol for\nUIs. A room is a durable group/channel: its public conversation supports\nthreads, replies, explicit agent mentions, attachment references, search,\nreactions, pins, edits, soft deletion, reconnect history, and authoritative\nmetrics. Mentions communicate but never silently launch work; delegation,\nconsultation, and ownership handoff remain explicit operations. Worker attempts\nhave isolated transcripts, results return durably to the room coordinator, and\nthe owner can launch a validated graph with one `team.delegate` call. The same\ntool can update configured room membership or archive an idle room without\nbypassing the store's membership and active-run guards. It works in both default filesystem mode and optional\nConvex mode; it does not require Tideline or a SaaS control plane. The current\nConvex collaboration adapter is a single-owner Phase-1 scale profile whose\nretained core state must stay below its documented 16 MiB hydration boundary;\nfilesystem mode does not have that Convex transaction limit.\n\nSee **[docs/team-mode.md](docs/team-mode.md)** for the execution model, agent\ntools, storage guarantees, and versioned WebSocket API. Brigade ships Team Mode\nas a headless backend so products can build their own web, desktop, or mobile\nroom experience without coupling UI code to the runtime package.\n\n---\n\n## Multi-agent isolation\n\nEvery agent has its own workspace, persona, credentials, memory, sessions, exec\napprovals, and routing bindings. By design:\n\n- Agent A cannot read agent B's session transcripts (unless visibility ≠ `self`).\n- Agent A cannot send to agent B's session unless `cfg.session.agentToAgent` (the\n A2A policy) permits it.\n- Memory facts are per-agent and origin-scoped — they don't bleed between agents.\n- Provider credentials are per-agent — e.g. `support` and `prod-bot` can use\n different accounts.\n\nThe default policy is `visibility: \"self\"` (an agent only sees its own sessions);\nswitch to `\"tree\"` to let a parent see sub-agents it spawned.\n\n---\n\n## Providers & web search\n\n**Models out of the box:** Anthropic, OpenAI, Google Gemini, OpenRouter, OrcaRouter, Token Market,\nGroq, Cerebras, xAI, DeepSeek, Mistral, **Ollama** (local), and **Custom**\nOpenAI-compatible endpoints (Together, Fireworks, vLLM, LM Studio, on-prem gateways\n— anything that speaks `/v1/chat/completions`). Connect several at once, switch with\n`/model`, and Brigade keeps your context across the switch.\n\n**Sign in with a subscription — no API key.** Don't want to manage keys, consoles,\nand billing? Use the subscription you already pay for. Two ways, both keyless:\n\n- **Browser sign-in** — `brigade login` signs in to **Claude Pro/Max**, **ChatGPT\n Plus/Pro**, or **GitHub Copilot** over OAuth (also offered inside `brigade onboard`).\n- **Reuse a CLI login** — already signed into the **Claude Code** or **Codex** CLI on\n this machine? `brigade onboard` offers *\"Reuse this machine's login\"* — one keystroke,\n no browser, no re-auth.\n\nKeys still work if you prefer them; either way the credential is sealed on your own\nmachine (auto-refreshed when the provider supports it).\n\nThe `claude-cli` provider goes one step further: it runs the `claude` binary as\nBrigade's engine, with the binary's own tools denied and **Brigade's guarded toolset\nserved back to it** over a per-turn loopback MCP endpoint. Your crew, your memory,\nyour approval prompts — on a subscription, at no marginal token cost. See\n[Subscription backends](#-subscription-backends--your-claude-login-brigades-tools).\n\n**Web search** is pluggable and auto-selected by what you've configured: Tavily,\nBrave, Exa, Perplexity, Firecrawl, SearXNG (keyed) and DuckDuckGo, Wikipedia, Hacker\nNews, arXiv, GitHub, npm, local Ollama (keyless).\n\n---\n\n## Configuration & storage\n\nBrigade keeps every byte of state under `~/.brigade/` — `rm -rf ~/.brigade` truly\nwipes everything it knows.\n\n```\n~/.brigade/\n├── brigade.json # main config (JSON5; ${VAR} secret refs preserved on write)\n├── brigade.json.bak{,.1..4} # rotating forensic backups (mode 0600)\n├── models.json # custom provider catalog (Ollama / custom endpoints)\n├── workspace/ # default agent (main): SOUL/IDENTITY/AGENTS/USER/TOOLS/\n│ │ # BOOTSTRAP/HEARTBEAT.md persona files\n│ ├── memory/facts.jsonl # write_memory / recall_memory\n│ └── skills/ # drop-a-folder skills\n├── agents// # per-agent isolation\n│ ├── workspace/ # same shape, per agent\n│ ├── sessions/.jsonl # transcripts (one file per session)\n│ └── agent/ # auth-profiles.json, models.json (mode 0600)\n├── channels/// # channel state (auth, allow-from, pairings)\n├── cron/runs/.jsonl # cron state + per-run logs\n├── logs/ # daily rolling logs + config audit\n└── gateway.{pid,lock,heartbeat}\n```\n\n**Useful environment overrides:**\n\n| Var | Purpose |\n|---|---|\n| `BRIGADE_STATE_DIR` | Alternate state directory (default `~/.brigade`) |\n| `BRIGADE_CONFIG_PATH` | Alternate config file path |\n| `BRIGADE_PORT` | Gateway port (default `7777`) |\n| `BRIGADE_PROFILE` | Named profile (`workspace-/`) |\n| `BRIGADE_MODE` | `filesystem` or `convex` |\n| `BRIGADE_CONVEX_URL` | Convex deployment URL (implies convex mode) |\n| `BRIGADE_ENCRYPTION_KEY` | At-rest encryption master key (hex) |\n| `BRIGADE_ENABLE_INBOX_PERSIST` | Persist the sub-agent inbox to JSONL (auto-on at gateway boot) |\n| `BRIGADE_HOST_ENV` | Override the host-environment tag in the system prompt's runtime line |\n\n---\n\n## Storage modes: filesystem vs. Convex\n\nBrigade defaults to **filesystem** mode (everything under `~/.brigade/`). It also\nships an optional **Convex** backend you can run **fully self-hosted** — no cloud\naccount, no telemetry. The mode resolves from a sticky sentinel and **freezes once\nat boot**.\n\n```bash\nbrigade store mode show # what mode am I in?\nbrigade store mode set convex --convex-url http://127.0.0.1:3210\nbrigade store migrate --to convex --dry-run # preview a migration\nbrigade store migrate --to filesystem # copy data back\n```\n\nRun the **bundled** self-hosted Convex backend — no Convex account, no separate\ninstall. The backend binary + functions ship inside Brigade, so this works from\nanywhere once `brigade` is installed, not just a repo checkout:\n\n```bash\nbrigade convex dev # download the backend if needed, then run it + dashboard (foreground)\nbrigade convex status # is the backend up? (probes :3210)\nbrigade convex push # deploy the bundled Convex functions to the backend\nbrigade convex codegen # regenerate convex/_generated/ against the local backend\n```\n\n`brigade convex dev` runs the backend on `:3210`, the site proxy on `:3211`, and\nthe dashboard on `:6791`, with binaries + data under `~/.brigade/convex/`. Ctrl-C\nto stop; the `brigade convex:dev` colon form works too. Then point Brigade at it\nwith `brigade store mode set convex --convex-url http://127.0.0.1:3210` (above).\n\n> Running from a repo checkout? The `npm run convex:install` / `convex:dev` /\n> `convex:codegen` scripts still work and write into the repo's `bin/` + `.convex-data/`.\n\nTurn on **at-rest encryption** for Convex byte columns (credentials, persona,\nmemory, cron payloads, transcripts) with `BRIGADE_ENCRYPTION_KEY`:\n\n```bash\nbrigade encrypt init # generate a 32-byte key\nbrigade encrypt status # is a key configured? self-check\nbrigade encrypt test # round-trip seal/open\n```\n\nSee [docs/convex-mode.md](docs/convex-mode.md) for the full runbook.\n\n---\n\n## MCP memory server\n\nBrigade can expose your long-term memory to any MCP client over stdio:\n\n```bash\nbrigade mcp # serves the `main` agent's memory\nbrigade mcp --agent support # a specific agent\n```\n\nIt surfaces add / search / context tools, owner-bound. Point an MCP client (an\neditor, a desktop assistant, etc.) at the command `brigade mcp`.\n\n---\n\n## Tideline (long-term memory)\n\nTideline is the **model-agnostic long-term memory engine** that backs Brigade.\nWhere a transcript is what an agent *just said*, Tideline is what it *knows* —\ndurable facts about you and your work, written under a trust gate, recalled by\nmeaning, decayed when stale, and reconciled over time. It's structured to be lifted\nout as its own package (`brigade-tideline`).\n\nIt's built to survive the three ways naive \"vector store\" memory breaks:\n\n| Pillar | What it does |\n|---|---|\n| 🛡️ **Provenance write-gate** | An untrusted source (a web page, a tool result) can't author or overwrite your identity/preferences/corrections. Poisoning writes are rejected. |\n| 🔒 **Per-origin isolation** | Owner facts and per-channel/peer facts are scoped so one principal's memory never surfaces in another's recall. |\n| 🔎 **Hybrid recall, no model needed** | BM25 keyword search + a **model-free** HRR vector recovery lane, so semantically-close phrasings match offline. Plug in a learned embedder to upgrade. |\n| ⏳ **Bi-temporal decay + trust** | Recency/usage decay and source-trust fold into one effective ranking score; `permanent` facts never decay. |\n| 🔗 **Typed link graph** | `supersedes` / `corrects` / `relates` / `supports` / `contradicts` edges power graph-recall and contradiction handling. |\n| 🌙 **Reflect / consolidate** | A nightly pass confirms repeated beliefs, merges duplicates, writes association edges, and evicts decayed noise. |\n\n**The flow, end to end:**\n\n```\nWRITE add() → write-gate (trusted vs untrusted × protected segment) → dedup → store\nRECALL query → BM25 + HRR vector → graph walk → decay×trust score → origin filter → budgeted block\nMAINTAIN decay GC → nightly dream (consolidate/relate) → contradiction detection\n```\n\nEach record carries a `segment` (identity / preference / correction / relationship /\nproject / knowledge / context), a `tier` (short / long / permanent), an `importance`,\nand an `origin`.\n\n```ts\nimport { Tideline } from \"brigade-tideline\";\n\nconst memory = Tideline.open(\"/path/to/workspace\");\nmemory.add({ content: \"I keep a strict vegetarian diet.\", segment: \"preference\" });\nconst block = memory.context(\"dietary restrictions\", { maxChars: 800 });\n```\n\nIn Brigade you reach it through the `recall_memory` / `read_memory` / `write_memory` /\n`manage_memory` tools and via auto-recall (which **fails closed** for unknown peers,\nso operator memory never leaks). An evaluation harness (`brigade-tideline/eval`)\nmeasures recall@k / MRR / nDCG@k on deterministic gold sets — run `npm run bench`.\n\n📖 Full write-up: **[docs/tideline.md](docs/tideline.md)** ·\npackage surface: [`src/tideline/`](src/tideline/)\n\n---\n\n## Extending Brigade\n\nBrigade ships a typed extension SDK. Drop a module into `~/.brigade/extensions/` and\nregister against a slot:\n\n```ts\nimport { defineModule } from \"@spinabot/brigade/extension-sdk\";\n\nexport default defineModule((b) => {\n b.tool({ /* a custom agent tool */ });\n b.webSearch({ /* a search provider */ });\n b.channel({ /* a messaging adapter */ });\n b.gatewayMethod({ /* a gateway RPC */ });\n});\n```\n\nShipped slots include `tool`, `hook`, `command`, `modelProvider`, `channel`,\n`webSearch`, `webFetch`, `integration`, `service`, `httpRoute`, and `gatewayMethod`.\nVoice/media slots (`tts`, `stt`, `mediaGen`) and pluggable `memory` backends have\nlocked contracts with implementations on the roadmap. See [AGENTS.md](AGENTS.md) for\nhow to add a tool, channel, skill, or provider.\n\n---\n\n## Privacy\n\nBrigade is a local CLI. Your API keys never leave your computer; they're stored in\nyour home directory at mode `0600` and used only to talk to the providers you\nconnect. **No telemetry, no analytics, no cloud component.** For Ollama and custom\nendpoints, requests stay on your network. The gateway binds to `127.0.0.1` by\ndefault.\n\n---\n\n## Develop from source\n\n```bash\ngit clone https://github.com/spinabot/brigade.git\ncd brigade\nnpm install\nnpm run build # tsc → dist/\n```\n\n**Run from your checkout** (npm scripts wrap the binary so you don't type `node`):\n\n```bash\nnpm run dev # smart runner: rebuilds dist/ if src/ is newer, then runs\nnpm run dev:tsx # run TypeScript directly via tsx (no build, slower per call)\nnpm run watch # tsx --watch: auto-restart on edit\nnpm link # make `brigade` available globally → this checkout\n```\n\n**Surface shortcuts** (all wrap `scripts/run-brigade.mjs`):\n\n```bash\nnpm run onboard # brigade onboard\nnpm run tui # brigade tui\nnpm run gateway # brigade gateway run (also gateway:status / gateway:stop)\nnpm run connect # brigade connect\nnpm run agent -- -m hi # brigade agent -m hi\nnpm run agents:list # brigade agents list (agents:add / agents:bind / …)\nnpm run status # brigade status (status:json)\nnpm run doctor # brigade doctor (doctor:json / doctor:strict)\nnpm run channels:list # brigade channels list (wa:link / pairing:list / …)\nnpm run skills:list # brigade skills list\nnpm run logs # brigade logs (logs:follow)\n```\n\n**Checks** (CI runs the same three):\n\n```bash\nnpm run typecheck # tsc --noEmit, strict\nnpm test # node:test, tempdir-isolated (281 test files)\nnpm run build # ensure the production build compiles\nnpm run bench # memory / recall evaluation benchmarks\n```\n\n**Storage / Convex dev:** `npm run store:mode:show`, `npm run convex:install`,\n`npm run convex:dev`, `npm run convex:codegen`.\n\nFull contributor guide, repo layout, and conventions live in **[AGENTS.md](AGENTS.md)**.\n\n---\n\n## Contributing\n\nContributions are welcome! Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup,\ncoding conventions, and the Conventional-Commits release flow. For security issues, see\n**[SECURITY.md](SECURITY.md)** — please report privately. Releases are automated with\nrelease-please; see **[docs/RELEASING.md](docs/RELEASING.md)**.\n\nQuestions or ideas? Open a\n[discussion](https://github.com/spinabot/brigade/discussions) or email\n**hello@brigade-agent.ai** (security → **security@brigade-agent.ai**).\n\n---\n\n## License\n\n[MIT](LICENSE) © Spinabot\n\n## 🦁 Brigadiers\n\nA pride of contributors who make Brigade better. Thank you to everyone who has\njoined the crew!\n\n\n![\"Bhasvanth-Dev9380\"](\"https://avatars.githubusercontent.com/u/157608971?v=4&s=48\")
![\"Bhasvanth-Spinabot\"](\"https://avatars.githubusercontent.com/u/314351905?v=4&s=48\")
![\"Ranjithsingh2004\"](\"https://avatars.githubusercontent.com/u/122562396?v=4&s=48\")
![\"FitBBC\"](\"https://avatars.githubusercontent.com/u/2372724?v=4&s=48\")
![\"ssh-den\"](\"https://avatars.githubusercontent.com/u/103561857?v=4&s=48\")
![\"viveknadig\"](\"https://avatars.githubusercontent.com/u/96881767?v=4&s=48\")
![\"dulcestentaciones2920-debug\"](\"https://avatars.githubusercontent.com/u/321300431?v=4&s=48\")
\n\n\nWant to join the pride? See [CONTRIBUTING.md](CONTRIBUTING.md).\n","readmeFilename":"README.md"}