# BrainOS

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6 repo stars
- Author: brainOS-HQ
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/brainOS-HQ/brain-os
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/brainos

## What it 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`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add brain-os -- npx -y brain-os
```

### Codex

**Platform CLI**
```bash
codex mcp add brainos -- npx -y brain-os
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "brainos": {
            "command": "npx",
            "args": [
                "-y",
                "brain-os"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "brainos": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "brain-os"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add brainos npx -y brain-os
```

## When to use it
- 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
- 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

## Similar
- [git-context-controller](https://affpapa.org/en/nevibecode/skills/git-context-controller.md) — skill · 82 installs
- [context-sync](https://affpapa.org/en/nevibecode/mcp/context-sync.md) — MCP server · ★ 190 repo stars
- [Vulcanus](https://affpapa.org/en/nevibecode/mcp/vulcanus.md) — MCP server · ★ 6 repo stars
- [mem-forever](https://affpapa.org/en/nevibecode/plugins/mem-forever.md) — plugin · ★ 28 repo stars
- [claude-mem](https://affpapa.org/en/nevibecode/plugins/claude-mem.md) — plugin · ★ 118868 repo stars
- [infernoflow](https://affpapa.org/en/nevibecode/mcp/infernoflow.md) — MCP server · ★ 10 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
