Brigade: a self-hosted agent crew with an org chart and a filesystem you own

The org chart is the architecture, not an org chart metaphor

Brigade describes itself as a crew of AI agents on a real org chart, and the documentation treats that structurally rather than as a description of how they are prompted.

Agents are spawned with their own personas, credentials and memory, and the org chart governs who can talk to whom. That last clause is the load-bearing one. Communication between agents is permitted according to the hierarchy, so the arrangement determines what any given agent can observe and delegate to, rather than every agent sharing a flat context where everything is reachable from everything.

Each agent also gets an isolated workspace. The default agent's workspace can be redirected by a named profile to a path under the state directory, while per-agent workspaces are unaffected and each agent always has its own directory under agents/<id>/. That means two agents doing related work do not share a working directory by accident, which is the failure mode where one agent's intermediate files become another's input.

Isolated credentials per agent is the detail that makes multi-agent setups worth the complexity. The README states plainly that keys stay on your own machine and are never sent to a middleman, and the privacy claim rests on that separation. Whether credentials are genuinely per-agent rather than per-installation is worth verifying in your own configuration, since a shared key defeats the isolation that the rest of the design depends on.

The storage is one directory, ~/.brigade/, holding config, agents, sessions and logs.

Tideline is what makes several agents worth more than one

Tideline is the long-term memory engine.

Facts persist across sessions, and three properties are named: origin scoping, decay, and hybrid recall combining keyword and vector search. The README names origin scoping without defining it here, so check the Tideline section of the README for how it behaves across agents before relying on it.

Decay is the other. Memory that only accumulates becomes a liability: something learned in one context persists and gets applied in another where it is wrong.

The hybrid recall is the practical part. Keyword search alone misses paraphrase and vector search alone misses exact identifiers, and an agent holding your file names and your account numbers needs both behaviours.

Tideline is exposed as an MCP server as well, so any MCP client can read your long-term memory. That is a genuine convenience and it is also the widest door in the design: memory readable by any MCP client is memory readable by whatever that client is connected to, and it is worth deciding deliberately which clients get access rather than wiring it everywhere by default.

The installation is a curl pipe, which is the first thing to think about

The stated install path is one line:

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

No sudo is used, and Node is installed if it is missing. Running an installer fetched over HTTPS means the script's contents can change between the moment you read about it and the moment you run it, which is a supply-chain consideration rather than a criticism of this particular script.

The alternative is to install from npm as @spinabot/brigade, which is what the package metadata describes: type module, a bin entry pointing at brigade.mjs, and an exports map with the root, an extension-sdk and a channel-sdk. Both subpath exports ship their own type declarations, which is what a consumer embedding either contract needs.

The package files list is worth reading as a description of what actually ships. Alongside the entry point and dist, it includes the run-brigade, build-done, install-convex, convex-dev, convex-push and brand-oauth-page scripts, the Convex TypeScript sources with their generated directory, the templates and skills directories, and one documentation file. So the distributed artefact is an application with bundled skills and templates rather than a library, and the convex sources shipping means the optional backend is inspectable after install rather than hidden on a server.

Development from source is a TypeScript build, tsc -p tsconfig.build.json, with a postbuild step and a watch variant.

Configuration is entirely optional, which cuts both ways

The .env.example opens by stating that every entry is optional and that Brigade boots with sensible defaults when nothing is set, and that it reads the live process.env rather than that file, with loaders such as dotenv populating process.env before startup. A stale or absent .env is described as always safe.

That design is correct for the case it targets, which is a single user installing on their own machine. The documented variables fall into groups that show the shape of the system: storage and paths, with BRIGADE_STATE_DIR for per-tenant isolation or an alternate install, BRIGADE_CONFIG_PATH to share one config across state directories, BRIGADE_PROFILE for a named workspace profile, and BRIGADE_BUNDLED_SKILLS_DIR which is described as something test fixtures use and advanced users leave unset.

BRIGADE_STATE_DIR being the isolation lever is the line to note. One directory holds config, agents, sessions, logs and credentials, so isolating two Brigade installations from each other means giving them separate state directories, not separating their configuration files. In a deployment with more than one tenant or one user account, that is the setting that matters.

The same directory being both state and secret store is the structural consequence. Backup routines, container volume mounts and file permissions all have to treat it as sensitive, and an operator who has internalised that a config directory is usually harmless will get this one wrong.

Connectors and channels are where the blast radius lives

The connector story is a count, and a thousand-plus connectors through a built-in Composio tool covering Gmail, Slack, GitHub, Notion, Calendar and Linear. The channel story is a list: WhatsApp, Telegram, Slack, Discord, iMessage and BlueBubbles today, with an adapter contract described as built for more.

Both are convenience, and both are attack surface. An agent that can read your mail and post to your Slack can act on content from a third party, and the described mitigation is that privileged actions wait for your approval. Approval gating is the right default here, and it is the difference between a system that needs constant supervision and one that is merely inconvenient.

The granularity of approval is worth checking. Whether approval is per tool, per integration, per destination or per session changes the practical burden enormously, and it is the question to answer before deploying rather than after. A prompt asking to read a calendar is low risk; a prompt asking to post to a channel your team reads is not, and a system that asks once for the whole session treats them the same.

The document handling claim is separate and notable: send a PDF, Office document, image, audio or video and the crew understands it, then creates or edits Word, Excel, PowerPoint and PDF files and hands them back. Read and write rather than read only, which doubles the value for office work and also means a misbehaving agent can produce files that look finished.

Bring any model, and that is the part with a moving target underneath

The provider list is long and includes names most people will not use: Anthropic, OpenAI, Gemini, OpenRouter, OrcaRouter, Token Market, Groq, Cerebras, xAI, DeepSeek, Mistral, local Ollama, or any OpenAI-compatible endpoint, with switching mid-conversation supported.

The OpenAI-compatible endpoint catch-all is the technically important entry, because it is what makes local models and self-hosted gateways work rather than each requiring an adapter. It is also the entry with the least specification, since a provider claiming compatibility may differ on the details that matter.

Switching mid-conversation without losing the thread is a stronger claim than it sounds. Preserving a task across a model change means the state lives in Brigade rather than in the model's context, which is the same design decision that makes Tideline necessary. If the thread is preserved by the framework, a weaker or smaller model can pick up a task a larger one started, and that is the practical case where this matters.

Authentication is described as needing no tokens to juggle: sign in with a Claude, ChatGPT or Copilot subscription, or reuse an existing Claude Code or Codex CLI login with no browser and no re-auth. That is convenient and it is a dependency on those services' subscription terms continuing to permit it, which is not this project's call to make.

The repo also carries AGENTS.md at the root and a CHANGELOG.md, plus a .release-please-manifest.json, which indicates releases are automated by release-please rather than cut by hand.

The bloody benchmark exposes agents deliberately, and the name undersells the risk

Brigade has a command called brigade bloody benchmark, introduced in v1.9.0, described as throwing your crew at strangers: exposing agents to the open internet with no net, so that what gets tested is whether unknown people poking your agents at three in the morning does not break them.

The framing is that the real threat model is an adversarial public endpoint, not a lab. That is a defensible position for a tool whose main draw is exposing a crew to chat channels, and the commands given are brigade bloody benchmark, brigade expose, and brigade expose stop.

What is described underneath is the opposite of careful. HTTPS at the edge, no account and no setup, Cloudflare by default or your own relay from a list of three open-source options. A secret key rides along invisibly, you never see it, and unauthorised requests get a 401.

Three things to check before running this. First, a key that is hidden from you may be hard to audit or revoke yourself, and understanding where it is stored matters before it is in production. Second, exposing an agent with connectors to the open internet means a stranger can attempt to induce the connectors to act, and the approval gate described earlier becomes the only thing between them and your Gmail. Third, the relay choice is a trust decision, since bring-your-own relay puts a tunnel component in the path that a default CDN would otherwise handle.

The README intro frames success only as surviving strangers poking at your agents, so check the rest of the README before treating the command as a test with a defined pass mark rather than an event.

It is not hosted, so you operate the upgrades, the backups and the permissions

Four boundaries.

It is not a hosted service, which is the whole premise and also the whole cost. There is no account and no SaaS in the middle, and that means you operate the thing: upgrades, backups, the state directory's permissions, and the version compatibility between the core and whatever Convex backend you run.

It is not a single-agent tool with extra steps. The org chart, isolation and shared memory are the feature, and a single task with one model does not need any of it. If your use is one agent answering questions against documents, this is a large system for that.

The Convex backend is optional and that cuts both ways. The default filesystem mode has no moving parts, and a self-hosted Convex with at-rest encryption is available when you want one database instead. What it means is two deployment shapes to understand,, and the filesystem default is the one most people will start with.

The privacy statement is that keys and data never leave your machine and there is no telemetry; that is the project's own claim, and SECURITY.md at the repository root is where to look for the security policy.

Before deploying: confirm the Node version requirement, decide whether the state directory needs to be something other than a home directory, check the approval granularity, and read SECURITY.md. Then run it on a machine with no credentials configured, because the system is designed to boot with defaults and that is the state in which to see what it actually does.

Editorial conclusion

Adopt Brigade if you want agents that share memory across sessions, run under your own storage, and can be reached from a terminal rather than a web console. Skip it if you need to know exactly what runs on your machine before an agent touches anything, because an agent with connectors and privileged actions that waits for approval still reaches Gmail, GitHub and Slack once approved. Before deploying it anywhere shared, read SECURITY.md and decide whether ~/.brigade holding credentials for many integrations belongs under one user account or needs isolation, because that directory is both the state and the secret store.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spinabot/brigade on GitHub