brigade

module

v0.20.0 Latest Latest Go to latest Published: Oct 4, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/appshapes/brigade

Links

Open Source Insights

README ¶

Brigade

Team messaging between the Claude Code sessions of different people and machines. Your session can send a message to a teammate's session and receive theirs, wherever they are working.

Two minutes of it, with two people's sessions:

If you want to

If you want to	Go to
install the plugin	Install
join a team, or a second repository of one	Join
update the plugin	Update
see the team's sessions (all, this repository's, or one member's), message one, keep your own roster line current	`plugin/README.md` › What teammates see about your session
hear a sound, or see a desktop notification, when a message arrives	Be told when a message arrives
check whether your session is receiving	`plugin/README.md` › Is my session receiving?
know what happens when the network drops	`plugin/README.md` › When the network drops
set a plugin option — or have your session set it for you	`plugin/README.md` › Options
hold messages for your review before your session sees them	`docs/setup.md` › Holding messages for review
change the sentence your sessions receive with each message	`docs/setup.md` › The frame text your sessions receive
sync folders between teammates' checkouts	Sync folders
let people on email or Slack take part: QA, product, anyone without a session	Let people on email or Slack take part
create a team	Create a team
add a repository to the team	Add a repository to the team
create the database, once per organization	Create a database
rotate the join secret, revoke a member, transfer the team	`docs/setup.md` › Team administration
leave a team, or uninstall	`docs/setup.md` › Leaving and uninstalling
know what Brigade protects, and what it does not	`docs/security.md`
see what changed in a release	`CHANGELOG.md`
write an adapter, or work on Brigade	`docs/adapter-authors.md`, `docs/development.md`

Install

Open Claude Code in a project that uses Brigade, and trust the folder when it asks.
Type /plugin install brigade@brigade. When it asks where to install, choose user.
Type /reload-plugins.

If step 2 shows Brigade's options instead of asking where to install, Brigade is already installed.

Join

Save the team's secret file that your administrator sent you somewhere outside the project folder.
In the project, type /brigade:join <path-to-that-file>.
In any other clone or repository of the same team, type /brigade:join — no file needed.

From then on your sessions in that project start connected. Type /brigade:sessions to see who is on the team.

Update

Nothing to do. Claude Code updates Brigade in the background and tells you to type /reload-plugins; do that. To update right away, type /brigade:update, then /reload-plugins.

Create a team

For administrators: a Supabase project, one brigade team create, the .brigade.json it writes into the repository, and the secret file you send each member — docs/setup.md › Administrator: create a team.

Add a repository to the team

Commit the team's .brigade.json at the top of the other repository, together with the .claude/settings.json marketplace entry, and join it once — docs/setup.md › The project owns the team.

Sync folders

List folders in the project's .brigade.json — "sync": { "folders": ["docs/shared"] } — and commit it. Every teammate's checkout of the repository keeps them in step, peer to peer through Syncthing, while a session is active; each machine needs syncthing on its PATH. brigade sync status shows what is syncing, and the plugin option sync: off switches it off — docs/sync.md.

Let people on email or Slack take part

People without a session, such as QA or product, can write to the team's sessions by email or from Slack, and sessions write back. Each gateway is one more member of the team, hosted in the team's own Supabase project. Nothing runs on anyone's machine.

For administrators, after make backend-install and brigade team create:

Email: make gateway-install project=<ref> from='Brigade <brigade@your-domain.com>', with SUPABASE_ACCESS_TOKEN and a Resend API key in the environment.
Slack: make slack-gateway-install project=<ref> twice. The first run prints a Slack app manifest to paste at api.slack.com; the second reads the app's token and signing secret from a file you name.
Commit the .brigade.json each run changed. Members need plugin 0.18.0 or later.

People then email the gateway's address, or message its Slack bot, with a first line to: <session>. Sessions write to a person by sending to the gateway with a first line to: <address>, to: @name or to: #channel. Step by step: docs/mail-gateway.md, docs/slack-gateway.md.

Be told when a message arrives

Ask your session:

Turn on message_sound and message_notification.

It edits your user settings. Start a new session for the change to take effect.

message_sound: a quiet sound when a teammate's message arrives. Off by default.
message_notification: a desktop notification naming the session the message was for. Off by default.
message_interval: the least seconds between two sounds, or two notifications. 30 by default; 5 to 3600.

Nothing from the message reaches either program. A project cannot set these options. Details: plugin/README.md › Options.

Create a database

Once per organization, by an administrator: a Supabase account and a project that stores your teams and their messages — the project settings, make backend-install, and the daily keep-alive that stops a free project pausing — docs/setup.md › Hosted project: the administrator's responsibilities.

More

docs/setup.md — the full guide: install and update in detail, options, leaving, team administration, the hosted backend
docs/security.md — what Brigade protects, what it does not, and what was measured
plugin/README.md — the plugin's commands and options
docs/sync.md — syncing a project's folders between teammates' checkouts
docs/mail-gateway.md, docs/slack-gateway.md — people on email or Slack taking part in a team
docs/adapter-authors.md — writing an adapter for another backend; the protocol is docs/protocol-v1.md; docs/sync-adapters.md is the same for a sync engine other than Syncthing
docs/development.md — working on Brigade: setup, an if-you-want-to table, gates, releases, layout, notes for adapter contributors
docs/claude-code-usage.md — working on Brigade with Claude Code: agents, skills, the Trello CLI
CHANGELOG.md — what changed in each release

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
brigade command Command brigade is the one shipped Brigade binary: the human and model command surface, the Claude Code lifecycle hooks, the detached watcher and the bundled adapters, all in one multi-call image (D35).	Command brigade is the one shipped Brigade binary: the human and model command surface, the Claude Code lifecycle hooks, the detached watcher and the bundled adapters, all in one multi-call image (D35).
brigade-adapter-fs command Command brigade-adapter-fs is the Brigade filesystem adapter: a second BAP/1 implementation whose backend is a directory on disk (plan P1-5).	Command brigade-adapter-fs is the Brigade filesystem adapter: a second BAP/1 implementation whose backend is a directory on disk (plan P1-5).
brigade-conformance command Command brigade-conformance runs the BAP/1 conformance suite (C-01..C-47, plan 9.2) against any adapter.	Command brigade-conformance runs the BAP/1 conformance suite (C-01..C-47, plan 9.2) against any adapter.
brigade-fake-adapter command Command brigade-fake-adapter is a scripted BAP/1 adapter used only as a test fixture (plan 9.5; brief section 2.10).	Command brigade-fake-adapter is a scripted BAP/1 adapter used only as a test fixture (plan 9.5; brief section 2.10).
brigade-schema command Command brigade-schema writes the Brigade Adapter Protocol JSON Schema document to stdout.	Command brigade-schema writes the Brigade Adapter Protocol JSON Schema document to stdout.
docs
research/plugin-bootstrap-cli.files command
internal
adapterkit Package adapterkit is the shared plumbing every Brigade adapter uses (plan P1-3): the bounded stdin document reader with its TTY refusal, the result printer (the only place under internal/ that may write protocol output to os.Stdout, plan 7.3), the XDG directory resolution of 3.2, the atomic 0600 file writer and the strict 0600 reader (U-10), the advisory flock helper on a sidecar file with its 10 s bound (5.1, corrected by E0-6), the O_EXCL pidfile helper with compare-then-delete removal (E0-5), and the profile file schema of 5.2.	Package adapterkit is the shared plumbing every Brigade adapter uses (plan P1-3): the bounded stdin document reader with its TTY refusal, the result printer (the only place under internal/ that may write protocol output to os.Stdout, plan 7.3), the XDG directory resolution of 3.2, the atomic 0600 file writer and the strict 0600 reader (U-10), the advisory flock helper on a sidecar file with its 10 s bound (5.1, corrected by E0-6), the O_EXCL pidfile helper with compare-then-delete removal (E0-5), and the profile file schema of 5.2.
adapterkit/log Package log is Brigade's one redacting slog handler (plan 7.3, T12): every diagnostic line an adapter or the harness writes to stderr or a log file goes through it, because the harness captures adapter stderr at debug level and a leak here puts a credential in a 0600-but-still- on-disk log file (U-09, U-23).	Package log is Brigade's one redacting slog handler (plan 7.3, T12): every diagnostic line an adapter or the harness writes to stderr or a log file goes through it, because the harness captures adapter stderr at debug level and a leak here puts a credential in a 0600-but-still- on-disk log file (U-09, U-23).
adapters/fs Package fs implements the Brigade filesystem adapter: a second BAP/1 implementation whose backend is a directory on disk.	Package fs implements the Brigade filesystem adapter: a second BAP/1 implementation whose backend is a directory on disk.
adapters/supabase Package supabase is the bundled Brigade adapter for a Supabase backend (plan section 5, protocol docs/protocol-v1.md): one anonymous GoTrue principal per profile, every write through the `brigade.*` RPCs of the finished migrations over PostgREST, and a Phoenix channel over coder/websocket for the watch.	Package supabase is the bundled Brigade adapter for a Supabase backend (plan section 5, protocol docs/protocol-v1.md): one anonymous GoTrue principal per profile, every write through the `brigade.*` RPCs of the finished migrations over PostgREST, and a Phoenix channel over coder/websocket for the watch.
app Package app is the multi-call dispatch seam of the shipped `brigade` binary: one process image serving the human command table, the Claude Code lifecycle hooks, the detached watcher and the bundled adapters (D35, 7.1).	Package app is the multi-call dispatch seam of the shipped `brigade` binary: one process image serving the human command table, the Claude Code lifecycle hooks, the detached watcher and the bundled adapters (D35, 7.1).
buildinfo Package buildinfo carries the version string of the running binary.	Package buildinfo carries the version string of the running binary.
cli Package cli holds the `brigade` command table, the interspersed-flag parser of plan 7.3, the usage and help output, and the mapping from a command failure to a process exit status (4.6).	Package cli holds the `brigade` command table, the interspersed-flag parser of plan 7.3, the usage and help output, and the mapping from a command failure to a process exit status (4.6).
conformance Package conformance is the BAP/1 conformance suite of plan 9.2: the library behind the dev binary cmd/brigade-conformance and behind the `go test` subtests of suite_test.go (TestConformanceFS/C-25), so that `go test ./...` stays a complete gate on its own.	Package conformance is the BAP/1 conformance suite of plan 9.2: the library behind the dev binary cmd/brigade-conformance and behind the `go test` subtests of suite_test.go (TestConformanceFS/C-25), so that `go test ./...` stays a complete gate on its own.
conformance/cases Package cases holds the conformance cases of plan 9.2, one file per case, coded against the T API of internal/conformance.	Package cases holds the conformance cases of plan 9.2, one file per case, coded against the T API of internal/conformance.
harness/account Package account reads the Claude account's email address from Claude Code's own configuration file, best effort and READ-ONLY (Trello card 24, part B): the `oauthAccount.emailAddress` string in `.claude.json`, which Claude Code keeps at $CLAUDE_CONFIG_DIR/.claude.json when that variable is set and at $HOME/.claude.json otherwise (E0-5, E0-7 — E0-7 also records a fresh config directory whose `.claude.json` has no `oauthAccount` key at all, which is exactly the "" case below).	Package account reads the Claude account's email address from Claude Code's own configuration file, best effort and READ-ONLY (Trello card 24, part B): the `oauthAccount.emailAddress` string in `.claude.json`, which Claude Code keeps at $CLAUDE_CONFIG_DIR/.claude.json when that variable is set and at $HOME/.claude.json otherwise (E0-5, E0-7 — E0-7 also records a fresh config directory whose `.claude.json` has no `oauthAccount` key at all, which is exactly the "" case below).
harness/adapterclient Package adapterclient is the one place the harness spawns an adapter child (plan 3.4, 4.1, 6.6; brief section 2.2).	Package adapterclient is the one place the harness spawns an adapter child (plan 3.4, 4.1, 6.6; brief section 2.2).
harness/backoff Package backoff is the retry arithmetic of plan 6.6 and 6.8 item 7 (U-16): an exponential schedule with jitter for the watcher's restart of its `message watch` child (1 s doubling to a 30 s cap, and a fixed 5 min once that pace has failed ten times — card 34) and for adapter errors (1 s doubling to a 5 min cap), and the retryability predicate — only `rate_limited` and `unavailable` (and a crash or signal, which adapterkit.Spawn already maps to `unavailable`) are ever retried; `invalid_input`, `unauthorized`, `loop_detected` and every other code are terminal.	Package backoff is the retry arithmetic of plan 6.6 and 6.8 item 7 (U-16): an exponential schedule with jitter for the watcher's restart of its `message watch` child (1 s doubling to a 30 s cap, and a fixed 5 min once that pace has failed ten times — card 34) and for adapter errors (1 s doubling to a 5 min cap), and the retryability predicate — only `rate_limited` and `unavailable` (and a crash or signal, which adapterkit.Spawn already maps to `unavailable`) are ever retried; `invalid_input`, `unauthorized`, `loop_detected` and every other code are terminal.
harness/bootstrap Package bootstrap holds no Go code that ships.	Package bootstrap holds no Go code that ships.
harness/commands Package commands implements the human and model command surface of the `brigade` binary (plan 6.4): `sessions`, `send`, `whoami`, `doing` (card 25, doing.go), `sync status` (card 33, sync.go), `team members`, the hold policy's `inbox` and `inbox release` (inbox.go), and the terminal pass-through of `team create\|join\|leave` and `profile init\|status\|reset\|revoke-credentials`.	Package commands implements the human and model command surface of the `brigade` binary (plan 6.4): `sessions`, `send`, `whoami`, `doing` (card 25, doing.go), `sync status` (card 33, sync.go), `team members`, the hold policy's `inbox` and `inbox release` (inbox.go), and the terminal pass-through of `team create\|join\|leave` and `profile init\|status\|reset\|revoke-credentials`.
harness/config Package config is the only harness package that reads configuration from the environment (plan 3.2, 6.5, 7.3; forbidigo enforces the static half).	Package config is the only harness package that reads configuration from the environment (plan 3.2, 6.5, 7.3; forbidigo enforces the static half).
harness/doing Package doing holds what the harness knows about a session's doing line (card 25, plan .context/plans/session-doing.md): the one sentence a session's own model publishes as `session_description` so teammates can route by it.	Package doing holds what the harness knows about a session's doing line (card 25, plan .context/plans/session-doing.md): the one sentence a session's own model publishes as `session_description` so teammates can route by it.
harness/e2e Package e2e holds the end-to-end harness tests of plan 9.5 (the integrator's half of P3-3/P3-4/P3-5, E2E-01's fs precursor): the built `brigade` binary and the built fs adapter, driven as real processes — the terminal pass-through that creates and joins a team, the three lifecycle hooks with their stdin documents and session environments, the REAL detached watcher the SessionStart hook spawns, `brigade send` from a second principal's own session, the frame arriving at a fake inbox socket, and the token appearing in no file and on no argv afterwards (U-25's whole-tree grep).	Package e2e holds the end-to-end harness tests of plan 9.5 (the integrator's half of P3-3/P3-4/P3-5, E2E-01's fs precursor): the built `brigade` binary and the built fs adapter, driven as real processes — the terminal pass-through that creates and joins a team, the three lifecycle hooks with their stdin documents and session environments, the REAL detached watcher the SessionStart hook spawns, `brigade send` from a second principal's own session, the frame arriving at a fake inbox socket, and the token appearing in no file and on no argv afterwards (U-25's whole-tree grep).
harness/foldersync Package foldersync is the harness side of the sync-adapter protocol (folder-sync plan §4.3, docs/sync-adapters.md): the request and result shapes of its five verbs, the Client that resolves a sync adapter by NAME and runs one verb through adapterkit.Spawn, and the derivations both ends of a team must agree on byte for byte — the folder id, path and label handed to `apply`, and the `<adapter>:<descriptor>` form a session's peer takes on the wire (sync_peer, C-47).	Package foldersync is the harness side of the sync-adapter protocol (folder-sync plan §4.3, docs/sync-adapters.md): the request and result shapes of its five verbs, the Client that resolves a sync adapter by NAME and runs one verb through adapterkit.Spawn, and the derivations both ends of a team must agree on byte for byte — the folder id, path and label handed to `apply`, and the `<adapter>:<descriptor>` form a session's peer takes on the wire (sync_peer, C-47).
harness/frame Package frame renders and parses the `<brigade-message>` frame of plan 6.7 — the text a receiving model actually reads — in the shape D19 settled on (variant C, decided by E0-3 at an interactive sitting on 2026-08-31): Brigade's own frame, nested by Wrap inside the native `<cross-session-message from-name="…">` wrapper that the Claude Code harness consumes into its "Message from @<name>" attribution.	Package frame renders and parses the `<brigade-message>` frame of plan 6.7 — the text a receiving model actually reads — in the shape D19 settled on (variant C, decided by E0-3 at an interactive sitting on 2026-08-31): Brigade's own frame, nested by Wrap inside the native `<cross-session-message from-name="…">` wrapper that the Claude Code harness consumes into its "Message from @<name>" attribution.
harness/hook Package hook implements the three Claude Code lifecycle hooks of plan 6.3 — `brigade hook session-start`, `brigade hook prompt` and `brigade hook session-end` — the processes Claude Code runs from plugin/hooks/hooks.json with a JSON document on stdin and the session's environment (6.5).	Package hook implements the three Claude Code lifecycle hooks of plan 6.3 — `brigade hook session-start`, `brigade hook prompt` and `brigade hook session-end` — the processes Claude Code runs from plugin/hooks/hooks.json with a JSON document on stdin and the session's environment (6.5).
harness/inbound Package inbound is the receive-side pipeline of plan 6.8 — the ordered controls every `message` event passes before it is framed and handed to an injector — implemented once, PURE, so that P3-5's watcher (socket post or `--sink`) and P3-4's prompt-hook poll (6.3) run the same code:	Package inbound is the receive-side pipeline of plan 6.8 — the ordered controls every `message` event passes before it is framed and handed to an injector — implemented once, PURE, so that P3-5's watcher (socket post or `--sink`) and P3-4's prompt-hook poll (6.3) run the same code:
harness/notice Package notice is the watcher's notice file (plan 3.2, card 34): the lines a watcher has for its session, which the next prompt hook prints once and removes.	Package notice is the watcher's notice file (plan 3.2, card 34): the lines a watcher has for its session, which the next prompt hook prints once and removes.
harness/notify Package notify resolves the fixed programs a session's watcher runs when a teammate's message arrives and the member asked to be told (cards 35 and 36): a quiet system sound through the platform's own player (`message_sound`), and a desktop notification through the platform's own notifier (`message_notification`).	Package notify resolves the fixed programs a session's watcher runs when a teammate's message arrives and the member asked to be told (cards 35 and 36): a quiet system sound through the platform's own player (`message_sound`), and a desktop notification through the platform's own notifier (`message_notification`).
harness/pidfile Package pidfile is the watcher's single-instance guard (plan 6.6, the `${BRIGADE_STATE_DIR}/watchers/<claude_pid>.json` row of 3.2, corrected by E0-5 items 1 and 3; package tree 7.1).	Package pidfile is the watcher's single-instance guard (plan 6.6, the `${BRIGADE_STATE_DIR}/watchers/<claude_pid>.json` row of 3.2, corrected by E0-5 items 1 and 3; package tree 7.1).
harness/policy Package policy decides the inbound policy a session runs under — the step 3 of plan 6.8, with the native `crossSessionInbound` scan of 6.10 folded in — and is the ONLY implementation of that decision: the SessionStart hook (P3-4) calls it to fill the by-pid map's `inbound`, the prompt-hook poll and the watcher's pipeline (internal/harness/ inbound) run under the value it produced.	Package policy decides the inbound policy a session runs under — the step 3 of plan 6.8, with the native `crossSessionInbound` scan of 6.10 folded in — and is the ONLY implementation of that decision: the SessionStart hook (P3-4) calls it to fill the by-pid map's `inbound`, the prompt-hook poll and the watcher's pipeline (internal/harness/ inbound) run under the value it produced.
harness/registry Package registry reads Claude Code's own session registry, best effort and read-only (plan 6.5, A.3): $CLAUDE_CONFIG_DIR/sessions/<pid>.json, an undocumented file that carries the session's display name (set with --name or /rename), its busy/idle status, the inbox socket path and the Claude Code version.	Package registry reads Claude Code's own session registry, best effort and read-only (plan 6.5, A.3): $CLAUDE_CONFIG_DIR/sessions/<pid>.json, an undocumented file that carries the session's display name (set with --name or /rename), its busy/idle status, the inbox socket path and the Claude Code version.
harness/sessionmap Package sessionmap is the hook-written state that binds a Claude Code process to its Brigade session (plan 3.2, 6.5): the by-pid map at ${stateDir}/sessions/by-pid/<claude_pid>.json, from which the session-bound commands and the watcher resolve EVERYTHING (profile, config dir, adapter argv, Brigade session id, team, socket path), and the by-native map at ${stateDir}/sessions/by-native/<claude_session_id>.json, which lets a later `claude --resume` re-open the same Brigade session (3.7).	Package sessionmap is the hook-written state that binds a Claude Code process to its Brigade session (plan 3.2, 6.5): the by-pid map at ${stateDir}/sessions/by-pid/<claude_pid>.json, from which the session-bound commands and the watcher resolve EVERYTHING (profile, config dir, adapter argv, Brigade session id, team, socket path), and the by-native map at ${stateDir}/sessions/by-native/<claude_session_id>.json, which lets a later `claude --resume` re-open the same Brigade session (3.7).
harness/socketpost Package socketpost is the inbox socket client of plan 6.7 and A.2: it writes one frame into a Claude Code session's `CLAUDE_CODE_MESSAGING_SOCKET` as the two NDJSON lines the harness reads — an auth line carrying the session's messaging token, then a user line carrying the content — and closes.	Package socketpost is the inbox socket client of plan 6.7 and A.2: it writes one frame into a Claude Code session's `CLAUDE_CODE_MESSAGING_SOCKET` as the two NDJSON lines the harness reads — an auth line carrying the session's messaging token, then a user line carrying the content — and closes.
harness/teamfile Package teamfile reads the one file a project may commit to name its Brigade team: `.brigade.json` at the repository toplevel (plan P7-2, brief §1).	Package teamfile reads the one file a project may commit to name its Brigade team: `.brigade.json` at the repository toplevel (plan P7-2, brief §1).
harness/teamstore Package teamstore is the user-side trust root of the repo-file model (plan P7-4, brief §3/§5): the team KEY that names a credential directory, the BINDING (`teams/<key>/team.json`, the adapterkit profile schema) verified field-by-field against a parsed repo file — the hash is never trusted alone — and the per-checkout PINS in `projects.json` that separate membership from attachment: a repo file attaches a session only where a human ran `team join` in that checkout.	Package teamstore is the user-side trust root of the repo-file model (plan P7-4, brief §3/§5): the team KEY that names a credential directory, the BINDING (`teams/<key>/team.json`, the adapterkit profile schema) verified field-by-field against a parsed repo file — the hash is never trusted alone — and the per-checkout PINS in `projects.json` that separate membership from attachment: a repo file attaches a session only where a human ran `team join` in that checkout.
harness/teamstore/write Package write holds every writer of the team store.	Package write holds every writer of the team store.