# spinabot/brigade architecture

> Architecture diagram of the GitHub repository spinabot/brigade, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spinabot/brigade
- Repository: https://github.com/spinabot/brigade

## Overview

Brigade is a self-hosted, multi-agent assistant reached through a terminal or messaging channels. A user message enters a channel adapter or the terminal client, reaches the gateway, and is handled in an agent session; the crew can use tools and shared Tideline memory, then return a response. The map also includes documented model/provider, collaboration, scheduling, MCP, and storage capabilities. Some implementations are represented by directory-level nodes because their source was not sampled; links without direct evidence are omitted.

Main entry points: [`src/core/server.ts`](https://github.com/spinabot/brigade/blob/main/src/core/server.ts) (WebSocket gateway), [`src/agents/agent-loop.ts`](https://github.com/spinabot/brigade/blob/main/src/agents/agent-loop.ts) (Agent loop), [`src/tui/client.ts`](https://github.com/spinabot/brigade/blob/main/src/tui/client.ts) (Terminal client), [`src/agents/channels`](https://github.com/spinabot/brigade/tree/main/src/agents/channels) (Messaging channels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_terminal["Terminal client<br/>[client.ts]"]
  node_channels["Messaging channels"]
  node_inbound["Inbound pipeline"]
end

subgraph group_runtime["Gateway runtime"]
  node_gateway["WebSocket gateway<br/>[server.ts]"]
  node_protocol["Wire protocol<br/>[protocol.ts]"]
  node_sessions[("Agent sessions<br/>[session-store.ts]")]
end

subgraph group_agents["Agents and capabilities"]
  node_agentloop["Agent loop<br/>[agent-loop.ts]"]
  node_providers["Model providers<br/>[catalog.ts]"]
  node_tools["Agent tools"]
  node_collaboration["Team coordination<br/>[runtime-service.ts]"]
  node_mcp["MCP tools<br/>[tool-plane-host.ts]"]
end

subgraph group_state["Memory and state"]
  node_tideline["Tideline memory<br/>[index.ts]"]
  node_memoryrecords[("Memory records<br/>[records.ts]")]
  node_storage[("Storage adapters")]
end

subgraph group_operations["Administration"]
  node_config["Configuration<br/>[io.ts]"]
  node_auth["Provider authentication<br/>[profiles.ts]"]
  node_scheduler["Cron scheduler<br/>[active-service.ts]"]
  node_tunnel["Secure exposure<br/>[manager.ts]"]
  node_convex[("Convex backend<br/>[schema.ts]")]
end

node_user(("User"))

node_user -->|"chats through"| node_terminal
node_user -->|"messages through"| node_channels
node_channels -->|"processes messages"| node_inbound
node_inbound -.->|"routes turns"| node_gateway
node_terminal -->|"sends requests"| node_gateway
node_terminal -->|"uses frames"| node_protocol
node_gateway -->|"handles methods"| node_protocol
node_gateway -->|"reads sessions"| node_sessions
node_gateway -->|"runs turns"| node_agentloop
node_agentloop -.->|"selects models"| node_providers
node_agentloop -.->|"invokes tools"| node_tools
node_agentloop -.->|"delegates tasks"| node_collaboration
node_gateway -->|"hosts tool plane"| node_mcp
node_gateway -->|"queries memory"| node_tideline
node_tideline -->|"stores facts"| node_memoryrecords
node_storage -.->|"supports backend"| node_convex
node_config -->|"resolves runtime mode"| node_storage
node_auth -->|"authenticates providers"| node_providers
node_gateway -->|"exposes cron methods"| node_scheduler
node_tunnel -->|"proxies access"| node_gateway

click node_terminal "https://github.com/spinabot/brigade/blob/main/src/tui/client.ts"
click node_channels "https://github.com/spinabot/brigade/tree/main/src/agents/channels"
click node_inbound "https://github.com/spinabot/brigade/blob/main/src/agents/channels/inbound-pipeline.ts"
click node_gateway "https://github.com/spinabot/brigade/blob/main/src/core/server.ts"
click node_protocol "https://github.com/spinabot/brigade/blob/main/src/protocol.ts"
click node_sessions "https://github.com/spinabot/brigade/blob/main/src/sessions/session-store.ts"
click node_agentloop "https://github.com/spinabot/brigade/blob/main/src/agents/agent-loop.ts"
click node_providers "https://github.com/spinabot/brigade/blob/main/src/providers/catalog.ts"
click node_tools "https://github.com/spinabot/brigade/tree/main/src/agents/tools"
click node_collaboration "https://github.com/spinabot/brigade/blob/main/src/collaboration/runtime-service.ts"
click node_mcp "https://github.com/spinabot/brigade/blob/main/src/agents/mcp/tool-plane-host.ts"
click node_tideline "https://github.com/spinabot/brigade/blob/main/src/tideline/index.ts"
click node_memoryrecords "https://github.com/spinabot/brigade/blob/main/src/tideline/store/records.ts"
click node_storage "https://github.com/spinabot/brigade/tree/main/src/storage"
click node_config "https://github.com/spinabot/brigade/blob/main/src/config/io.ts"
click node_auth "https://github.com/spinabot/brigade/blob/main/src/auth/profiles.ts"
click node_scheduler "https://github.com/spinabot/brigade/blob/main/src/cron/active-service.ts"
click node_tunnel "https://github.com/spinabot/brigade/blob/main/src/core/tunnel/manager.ts"
click node_convex "https://github.com/spinabot/brigade/blob/main/convex/schema.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_terminal,node_channels,node_inbound,node_user toneBlue
class node_gateway,node_protocol,node_sessions toneAmber
class node_agentloop,node_providers,node_tools,node_collaboration,node_mcp toneMint
class node_tideline,node_memoryrecords,node_storage toneRose
class node_config,node_auth,node_scheduler,node_tunnel,node_convex toneIndigo
```

## Components

### User entry

- [Terminal client](https://github.com/spinabot/brigade/blob/main/src/tui/client.ts): `src/tui/client.ts`
- [Messaging channels](https://github.com/spinabot/brigade/tree/main/src/agents/channels): `src/agents/channels`
- [Inbound pipeline](https://github.com/spinabot/brigade/blob/main/src/agents/channels/inbound-pipeline.ts): `src/agents/channels/inbound-pipeline.ts`

### Gateway runtime

- [WebSocket gateway](https://github.com/spinabot/brigade/blob/main/src/core/server.ts): `src/core/server.ts`
- [Wire protocol](https://github.com/spinabot/brigade/blob/main/src/protocol.ts): `src/protocol.ts`
- [Agent sessions](https://github.com/spinabot/brigade/blob/main/src/sessions/session-store.ts): `src/sessions/session-store.ts`

### Agents and capabilities

- [Agent loop](https://github.com/spinabot/brigade/blob/main/src/agents/agent-loop.ts): `src/agents/agent-loop.ts`
- [Model providers](https://github.com/spinabot/brigade/blob/main/src/providers/catalog.ts): `src/providers/catalog.ts`
- [Agent tools](https://github.com/spinabot/brigade/tree/main/src/agents/tools): `src/agents/tools`
- [Team coordination](https://github.com/spinabot/brigade/blob/main/src/collaboration/runtime-service.ts): `src/collaboration/runtime-service.ts`
- [MCP tools](https://github.com/spinabot/brigade/blob/main/src/agents/mcp/tool-plane-host.ts): `src/agents/mcp/tool-plane-host.ts`

### Memory and state

- [Tideline memory](https://github.com/spinabot/brigade/blob/main/src/tideline/index.ts): `src/tideline/index.ts`
- [Memory records](https://github.com/spinabot/brigade/blob/main/src/tideline/store/records.ts): `src/tideline/store/records.ts`
- [Storage adapters](https://github.com/spinabot/brigade/tree/main/src/storage): `src/storage`

### Administration

- [Configuration](https://github.com/spinabot/brigade/blob/main/src/config/io.ts): `src/config/io.ts`
- [Provider authentication](https://github.com/spinabot/brigade/blob/main/src/auth/profiles.ts): `src/auth/profiles.ts`
- [Cron scheduler](https://github.com/spinabot/brigade/blob/main/src/cron/active-service.ts): `src/cron/active-service.ts`
- [Secure exposure](https://github.com/spinabot/brigade/blob/main/src/core/tunnel/manager.ts): `src/core/tunnel/manager.ts`
- [Convex backend](https://github.com/spinabot/brigade/blob/main/convex/schema.ts): `convex/schema.ts`

### Other components

- **User**

## Connections

- User → Terminal client: chats through (evidence: `README.md`)
- User → Messaging channels: messages through (evidence: `README.md`)
- Messaging channels → Inbound pipeline: processes messages (evidence: `src/agents/channels/manager.ts`)
- Inbound pipeline → WebSocket gateway: routes turns
- Terminal client → WebSocket gateway: sends requests (evidence: `src/tui/client.ts`)
- Terminal client → Wire protocol: uses frames (evidence: `src/tui/client.ts`)
- WebSocket gateway → Wire protocol: handles methods (evidence: `src/core/server.ts`)
- WebSocket gateway → Agent sessions: reads sessions (evidence: `src/core/server.ts`)
- WebSocket gateway → Agent loop: runs turns (evidence: `src/core/server.ts`)
- Agent loop → Model providers: selects models
- Agent loop → Agent tools: invokes tools
- Agent loop → Team coordination: delegates tasks
- WebSocket gateway → MCP tools: hosts tool plane (evidence: `src/core/server.ts`)
- WebSocket gateway → Tideline memory: queries memory (evidence: `src/core/server.ts`)
- Tideline memory → Memory records: stores facts (evidence: `src/tideline/index.ts`)
- Storage adapters → Convex backend: supports backend
- Configuration → Storage adapters: resolves runtime mode (evidence: `src/config/io.ts`)
- Provider authentication → Model providers: authenticates providers (evidence: `src/auth/profiles.ts`)
- WebSocket gateway → Cron scheduler: exposes cron methods (evidence: `src/core/server.ts`)
- Secure exposure → WebSocket gateway: proxies access (evidence: `src/core/tunnel/manager.ts`)
