Skip to main content
MCP server CX Codex

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

Install into Claude Code · Platform CLI All methods and platforms ↓
claude mcp add brain-os -- npx -y brain-os
Open on GitHub

What 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-os

Step 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.

Similar MCP servers

All MCP servers for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open