Installation

Prerequisites

curl --version       # included on macOS/Linux
jq --version         # brew install jq  /  apt install jq
claude --version     # Claude Code CLI

Container runtime — podman or docker (with Compose support). The installer auto-detects whichever is available, preferring podman. Not required when using SKIP_MDPLANNER=1.

gh (GitHub CLI) is optional — needed for PR workflows only.

Install

One command installs everything:

curl -fsSL https://cerveau.dev/install.sh | bash

This will:

1. Download the packages to ~/.cerveau/
2. Install the cerveau CLI binary
3. Generate an MCP token and write it to ~/.cerveau/.env
4. Start MDPlanner via Podman or Docker
5. Register the MDPlanner MCP globally (--scope user) so every Claude Code session has it

Verify MDPlanner is running:

curl -s http://localhost:8003/health
# expected: {"status":"ok"}

Without MDPlanner (core-local)

If you prefer file-based task management (no server, no container runtime), skip the MDPlanner setup:

SKIP_MDPLANNER=1 curl -fsSL https://cerveau.dev/install.sh | bash

This installs the packages and CLI but skips steps 3–5. Use studiowebux/core-local instead of studiowebux/core when spawning brains:

cerveau spawn MyApp /path/to/code --packages studiowebux/core-local

core-local provides the same session phases, discipline rules, hooks, skills, and templates as core, but stores tasks, notes, and milestones as local markdown files inside the brain directory. No MDPlanner server, no container runtime, no network dependency — everything works offline.

Directory Layout

Everything lives in ~/.cerveau/ — your project repos are never touched:

~/.cerveau/
  _packages_/       ← shared rules, hooks, skills, agents, templates
  _brains_/         ← one directory per brain (created by cerveau spawn)
  _configs_/        ← brains.json registry, registry.json package catalog
  _scripts_/        ← helper scripts
  bin/cerveau       ← CLI binary
  .env              ← MDPLANNER_MCP_TOKEN (preserved across updates)
  docker-compose.yml

Brains vs Projects

A brain is a separate directory (~/.cerveau/_brains_/myapp-brain/) that holds the protocol, rules, and MDPlanner context for one project. Your project codebase stays wherever it already lives — untouched, in any directory, in any git repo.

The brain links to your code via additionalDirectories in its settings.json. No files are added to your project repos. You can have as many brains as you have projects, all sharing the same packages.

Environment Variables

Variable	Default	Description
CERVEAU_HOME	~/.cerveau	Where Cerveau installs packages, brains, and config
MCP_PORT	8003	Port MDPlanner listens on
SKIP_MDPLANNER	0	Set to 1 to skip MDPlanner setup (container, MCP token, MCP registration)
CERVEAU_SKIP_UPDATE_CHECK	0	Set to 1 to disable the automatic version check at session start
CERVEAU_SKIP_BINARY_UPDATE	0	Set to 1 to skip CLI binary download during cerveau update (packages and configs are still updated)

Set these before running the installer to override the defaults:

CERVEAU_HOME=/opt/cerveau MCP_PORT=9000 curl -fsSL https://cerveau.dev/install.sh | bash

Status Line (Optional)

Install the status line script after install:

cerveau install-statusline

Shell Completions (Recommended)

Enable tab-tab for all commands, brain names, and packages:

eval "$(cerveau completion zsh)"    # add to .zshrc
eval "$(cerveau completion bash)"   # add to .bashrc

This also enables cerveau cd brain|code <name> to navigate to brain or codebase directories.

Updating

Pull the latest packages without losing your config or brains:

cerveau update

Or from inside a brain session: /update

Backup & Restore

Create a backup of your environment:

cerveau backup                    # everything (default)
cerveau backup --cerveau          # brains, configs, packages, .env
cerveau backup --mdplanner        # MDPlanner data only
cerveau backup --claude           # ~/.claude/ (can be large)

Restore from a backup:

cerveau restore backup.tar.gz              # restore all sections in archive
cerveau restore backup.tar.gz --cerveau    # restore only cerveau section

See CLI Reference for all options.

Next

→ Quick Start