Architecture

Cerebro is a Rust workspace with four crates that share types and read from a common cortex data directory.

System overview

flowchart TB
    subgraph cerebro_repo["~/Projects/cerebro (source code)"]
        CLI_CRATE["crates/cerebro<br/>CLI binary"]
        CORE_CRATE["crates/cerebro-core<br/>shared types"]
        MCP_CRATE["crates/cerebro-mcp<br/>MCP library"]
        TUI_CRATE["crates/cerebro-tui<br/>TUI binary"]
        DOCS["docs/<br/>tool documentation"]
    end

    subgraph cortex_dir["~/Projects/<name> (your cortex)"]
        CFG["config.toml"]
        AUTO["content/ (auto-generated)<br/>index.md, projects/, journal/"]
        MANUAL["content/ (manual)<br/>intent/, notes/, SUMMARY.md"]
        BOOK["book/<br/>rendered HTML"]
        AGENTS["AGENTS.md<br/>edit boundaries"]
    end

    subgraph external["External data sources"]
        GIT["project git repos"]
        OODB["opencode sessions.db"]
    end

    subgraph consumers["Consumers"]
        MDBOOK["mdbook"]
        OPENCODE["OpenCode"]
        TERMINAL["Terminal user"]
    end

    CLI_CRATE -->|scrapes| GIT
    CLI_CRATE -->|queries| OODB
    CLI_CRATE -->|reads| CFG
    CLI_CRATE -->|writes| AUTO

    TUI_CRATE -->|reads same data| AUTO
    TUI_CRATE -->|reads| MANUAL
    TUI_CRATE -->|uses types| CORE_CRATE

    MCP_CRATE -->|reads| AUTO
    MCP_CRATE -->|reads| MANUAL

    MANUAL -. "human edits" .-> MANUAL
    AGENTS -. "defines boundaries" .-> MANUAL

    AUTO -->|mdbook src| MDBOOK
    MANUAL -->|mdbook src| MDBOOK
    MDBOOK -->|renders| BOOK

    OPENCODE <-->|JSON-RPC| MCP_CRATE
    TERMINAL <-->|interactive| TUI_CRATE

    style CLI_CRATE fill:#4a9eff,color:#fff
    style TUI_CRATE fill:#9b59b6,color:#fff
    style MCP_CRATE fill:#ff6b6b,color:#fff
    style AUTO fill:#ff8
    style MANUAL fill:#f8f
    style BOOK fill:#8f8

The two repos

cerebro at ~/Projects/cerebro

The source code repository. Contains:

• Command-line tool binary at crates/cerebro/: Scrapes data sources and generates markdown
• Shared types at crates/cerebro-core/: Config, ProjectContext, Storage trait, collectors, queries
• Model Context Protocol, or MCP, server at crates/cerebro-mcp/: JSON-Remote Procedure Call, or RPC, server for OpenCode
• Terminal User Interface, or TUI, at crates/cerebro-tui/: Ratatui terminal UI for interactive browsing
• Documentation at docs/: mdBook docs about the cerebro tool itself

Your cortex

The cortex, named whatever you choose: cortex in this project’s case. Contains:

• config.toml: Project list and settings. Read by cerebro.
• content/: mdBook source. A mix of auto-generated and manual content.
• book/: Rendered HTML output
• AGENTS.md: Defines edit boundaries for AI agents
• book.toml: mdBook configuration

The four binaries

cerebro, the command-line tool

cerebro build            # Scrape repos, generate markdown
cerebro build --fresh    # Ignore cache
cerebro build --project X  # Single project
cerebro status           # Show cache status
cerebro serve            # Spawn mdbook in output_dir
cerebro serve --port N   # Custom port
cerebro mcp              # Start MCP server
cerebro tui              # Launch terminal UI

Data flow:

1. Reads config.toml from your cortex
2. For each project: scrapes git, queries OpenCode DB, scans TODOs, reads manual notes
3. Writes markdown to output_dir. The default is ./content.
4. Cache stored alongside config to avoid redundant scraping

cerebro-mcp, the Model Context Protocol server

# Started by OpenCode via opencode.json:
#   "command": ["cerebro", "mcp"]
# Or standalone:
cerebro-mcp    # Reads CORTEX_PATH env var; falls back to ~/Projects/cortex

Tools provided:

• read_project: Combined generated + manual content for a project
• list_projects: All tracked projects with metadata
• read_journal: Journal entry by date
• read_today: Today’s journal entry
• read_intent: Goals by period. Options are daily, weekly, monthly, or yearly.
• search_todos: Search TODOs across projects
• get_stats: Overall statistics

Path resolution:

• CORTEX_PATH env var. Optional: points to the cortex data dir; falls back to ~/Projects/cortex if unset.
• Reads generated content from {CORTEX_PATH}/content/
• Reads manual notes from {CORTEX_PATH}/content/notes/ and {CORTEX_PATH}/content/intent/

cerebro-tui, the Terminal UI

Interactive terminal UI for browsing projects without opening a browser. Shares cerebro-core types with the command-line tool and reads the same cortex content that mdbook renders.

Views:

• Dashboard: Project overview with summary cards and scrollable project table
• Projects: Tabbed Sessions/Commits/TODOs per project, detail modals, manual note editor
• Journal: Date-grouped entries with activity indicators, entry editor
• TODOs: Cross-project table with project/keyword filter cycling, text search
• Config: Project list with active toggle, add-project form, Tom’s Obvious Minimal Language, or TOML, persistence

See TUI Architecture for the component pattern and data flow.

Content boundaries

The cortex’s content/ has a strict split between auto-generated and manual content:

Auto-generated: cerebro writes, humans don’t edit

Manual: humans write, cerebro doesn’t modify

An AGENTS.md file in your cortex enforces the boundary, instructing AI agents which files are safe to overwrite and which are human-only.

Cron workflow

0 5,9 * * *    cerebro build && mdbook build
59 23 * * *    cerebro build && mdbook build

Runs from your cortex. Scrape → generate → render, three times daily.

Shared type system

All binaries share types from cerebro-core:

ProjectConfig     : Name, repo_path, active flag
ProjectContext    : Full context: commits, sessions, todos, notes
ManualNotes       : Status, next actions, journal excerpt
Config            : Settings + project list
Cache             : Timestamps for incremental scraping

The TUI uses these same types to render views, ensuring consistency between what you see in the browser via mdbook, the terminal via the TUI, and what OpenCode reads via MCP.

Data flow pipeline

flowchart TD
    subgraph Config["Configuration"]
        C[config.toml]
    end

    subgraph Collect["Collectors"]
        O[OpenCode] --> S[Session history]
        G[Git] --> CMT[Commits, files]
        T[TODOs] --> TC[TODO/FIXME comments]
        N[Notes] --> MN[Manual notes]
    end

    subgraph Generate["Generators"]
        D[Dashboard] --> MD[Markdown]
        J[Journal] --> MJ[Markdown]
        P[Periodic] --> MP[Markdown]
        PR[Project] --> MPR[Markdown]
    end

    subgraph Out["Output"]
        ODIR[content/]
    end

    C --> Collect
    Collect --> Generate
    Generate --> Out

Collection sources

Crate details

cerebro

The main command-line tool binary. Entry point that:

• Parses command-line arguments via clap
• Coordinates collection and generation
• Manages the file-based cache
• Spawns the TUI and MCP server as subcommands

crates/cerebro/src/
├── main.rs          # Entry point, clap subcommands
├── cli.rs           # CLI argument definitions
├── config.rs        # Configuration loading
├── cache.rs         # Cache management
└── generators/      # Output generation (dashboard, project, journal, periodic)

cerebro-core

Shared library used by all other crates. Contains:

• Types: ProjectConfig, ProjectContext, ManualNotes, Config, Cache
• Traits: Storage, Git, Database for dependency injection
• Collectors: OpenCode, Git, TODO, and manual notes collection implementations
• Queries: Read operations used by command-line tool subcommands and MCP tools

crates/cerebro-core/src/
├── lib.rs           # Type definitions, re-exports
├── storage.rs       # Storage, Git, Database traits
├── collectors/      # Data collection implementations
└── queries/         # Read operations (projects, journal, todos, intent, stats)

cerebro-mcp

Model Context Protocol, or MCP, server for OpenCode integration. Provides JSON-RPC tools that allow AI assistants to query cortex data.

crates/cerebro-mcp/src/
├── server.rs        # MCP server setup and event loop
└── tools/           # Tool implementations (re-export cerebro-core queries)

cerebro-tui

Ratatui terminal UI for interactive project browsing. Uses the Component + Action pattern with async tokio event loop.

crates/cerebro-tui/src/
├── app.rs           # App struct, initialization
├── action.rs        # Action enum, View, KeyBinding, InputMode
├── tui.rs           # Terminal setup, event loop
├── cli.rs           # TUI-specific CLI args
├── errors.rs        # Error handling
├── lib.rs           # Library re-exports
└── components/      # UI components (home, dashboard, projects, journal, todos, config, sidebar, help, widgets)