BrainOS — Claude Code MCP server: what it does, how to install
BrainOS is an MCP server for Claude Code that preserves decisions, blockers, and plans across sessions. It tests proposed code changes against previously recorded architecture choices.
MIT ★ 6 updated 2026-11-17
claude mcp add brain-os -- npx -y brain-osWhat BrainOS does
BrainOS keeps operational project context inside a local .brain/ directory. Instead of storing entire conversation logs, it tracks structured entities, status, blockers, and settled decisions alongside rejected alternatives. When an agent proposes an architecture change, the decision_check tool verifies whether that choice contradicts an earlier agreement.
Repository setup runs via npx brain-os init or through the brain_setup tool inside chat. The initialization creates canonical instructions in AGENTS.md and registers slash commands such as /brain:focus and /brain:decide. It also includes an operational_state_check tool that inspects the current Git commit, branch, and package metadata without altering files.
The server requires Node.js 20 or newer. Core operations run completely offline without extra credentials, while semantic memory search requires the optional openai package and an OPENAI_API_KEY.
What it helps with
- track architectural decisions and rejected alternatives across chat sessions
- prevent agents from reopening settled engineering choices
- detect stale tasks and recurring blockers in project state
- inspect Git repository status and package versions without touching files
Example prompts for the agent
- Set up Brain OS in this project.
- /brain:decide Choose SQLite over Postgres for local storage
- Check our decision history before changing the database schema
How to install BrainOS
Platform CLI
claude mcp add brain-os -- npx -y brain-osPlatform CLI
codex mcp add brainos -- npx -y brain-osConfig file
{
"mcpServers": {
"brainos": {
"command": "npx",
"args": [
"-y",
"brain-os"
]
}
}
}Config file
{
"servers": {
"brainos": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"brain-os"
]
}
}
}Platform CLI
gemini mcp add brainos npx -y brain-osStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about BrainOS
How to install BrainOS in Claude Code?
To connect the server to Claude Code, run claude mcp add brain-os -- npx -y brain-os.
What does BrainOS do?
It stores project state in a .brain/ directory, tracks recorded decisions with rejected alternatives, and flags new agent proposals that contradict established project choices.
What is required to run BrainOS?
It requires Node.js version 20 or newer. Core features run without external dependencies, while the semantic_recall tool requires the openai package and an OPENAI_API_KEY.