Introduction

Cerebro is human-centric. The cortex is yours—plain markdown you can read, edit, and open in any tool. AI integration is optional, not a requirement.

The problem

You have side projects. Maybe 3, maybe 10. You work on them in bursts: a flurry of commits, then months of silence.

When you return, the question is always the same:

“Wait, what work was in progress? Where did things leave off?”

You scroll through git history. You grep for “TODO”. You search your notes. By the time you remember, you’ve already lost 20 minutes.

The solution

Cerebro watches your development activity and builds a personal mission control dashboard. It aggregates:

AI sessions: Your AI pair-programming history (OpenCode, Pi, or both)
Git activity: Commits, branches, file changes
TODOs: TODO, Needs Fixing, Hack, and Placeholder comments in your code
Manual notes: Your status, next actions, goals

When you return to a dormant project, your dashboard answers the question in seconds.

How it works

Cerebro uses a two-repo architecture:

flowchart LR
    subgraph "Sources"
        G[Git repos]
        O[AI sessions]
    end

    subgraph "cerebro (CLI)"
        C[cerebro build]
    end

    subgraph "cortex (your data directory)"
        CT[content/ generated md]
        NB[content/notes/ manual]
        BK[book/ rendered HTML]
    end

    subgraph "cerebro-mcp"
        MS[MCP server]
    end

    subgraph "cerebro-tui"
        TUI[Terminal UI]
    end

    subgraph "Consumers"
        TERM[Terminal user]
        MDB[mdbook]
        OC[OpenCode]
    end

    G -->|scrape| C
    O -->|scrape| C
    C -->|writes| CT
    NB -. manual .-> CT
    CT -->|mdbook| BK
    NB -->|mdbook| BK
    MS -->|reads| CT
    MS -->|reads| NB
    OC <-->|JSON-RPC| MS
    TUI -->|reads| CT
    TUI -->|reads| NB
    TERM <-->|interactive| TUI

The two repos

Repo	Purpose
`~/Projects/cerebro`	Source code: command-line tool, MCP, Terminal User Interface, shared types
`~/Projects/<name>`	Your cortex: config, generated content, manual notes, rendered HTML

The three binaries

Binary	Purpose	Used by
`cerebro`	Command-line tool: scrape repos, generate markdown	You, cron
`cerebro-mcp`	MCP server: answer questions about projects	Any MCP client
`cerebro-tui`	Terminal UI: browse projects interactively	You

Content boundaries

Your cortex’s content/ has a clear split:

Path	Generated by	Edit?
`content/index.md`	cerebro	No
`content/projects/*.md`	cerebro	No
`content/journal/`	cerebro	No
`content/today.md`	cerebro	No
`content/this-week.md`	cerebro	No
`content/intent/`	Human	Yes
`content/notes/`	Human	Yes
`content/SUMMARY.md`	Human	Yes

An AGENTS.md file in your cortex enforces the boundary. AI agents should not edit manual content.

Why it works

Cerebro succeeds when it reduces context-switching friction. You’ll notice it when:

You return to a project you haven’t touched in weeks
You have too many projects to track mentally
You use AI assistants and want to remember what you worked on

Key concepts

Term	Meaning
Collector	A source of data (git, opencode, todos, notes)
Generator	Creates output files from collected data
Project	A repo + notes + activity you’re tracking
Dashboard	The generated markdown output
Cortex	Your data directory: config, content, rendered book
Terminal User Interface	Terminal UI for interactive browsing

Architecture

Cerebro is a Rust workspace with four crates:

cerebro: Command-line tool: coordinates collectors and generators, manages cache
cerebro-core: Shared types, traits, collector implementations, and query operations
cerebro-mcp: MCP server for OpenCode integration
cerebro-tui: Ratatui terminal UI for browsing projects interactively

Next steps

Quick Start: Get running in 5 minutes
Dashboard Guide: Understand the output
Configuration: Customize for your projects

Keyboard shortcuts

Cerebro