Brains Reference / The supported surface
Find the command. Know the boundary.
The CLI and MCP operate on the same local coordination state. Choose the surface that fits how you are working.
Two entry points, shared meanings
- CLI commands
Use
brains-aifor terminal operations, setup and inspection. Learn the command families and check exact options with the installed--help. - MCP tools
Use the
brains_tools from a connected agent. Browse the full allowlisted inventory by purpose, including mailbox and peer-help lifecycle tools.
New to the workflow? Quickstart gets the service running; Coordination shows when to use these operations rather than simply listing them.
Read the nouns consistently
| Term | Meaning |
|---|---|
| Workspace | A repository or working directory that scopes coordination. |
| Session | A durable agent handle, not a process or a live-delivery guarantee. |
| Task / Claim | A unit of work and its bounded ownership. Claims do not lock files. |
| Handoff / Checkpoint | Stopping context and intermediate resume markers. |
| Knowledge | A reusable, scoped finding that another Session can search. |
| Mailbox / Peer help | Durable local correspondence and a separate claimable request lifecycle. |
| Ask / Decision | A question or approval reserved for human authority. |
Source defines support
The release-tagged capability allowlist defines the MCP surface and withdrawn command sets. Retained implementation code or old database tables are not activation paths. This reference does not advertise semantic indexing, code graphs, model routing, chat bridges or runtime execution.
Parameters can differ between similarly named CLI and MCP operations. The CLI implementation and full MCP contracts provide deeper detail. For authentication, destructive recovery and service limitations, read Operations.