Introduction

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 was I working on? Where did I 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:

OpenCode sessions — Your AI pair-programming history
Git activity — Commits, branches, file changes
TODOs — TODO, FIXME, HACK, XXX 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[OpenCode sessions.db]
    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"
        MDB[mdbook]
        OC[OpenCode]
        TERM[Terminal user]
    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 — CLI, MCP, TUI, shared types
`~/Projects/<name>`	Your cortex — config, generated content, manual notes, rendered HTML

The Four Binaries

Binary	Purpose	Used by
`cerebro`	CLI: scrape repos, generate markdown	You, cron
`cerebro-mcp`	MCP server: answer questions about projects	OpenCode
`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

The boundary is enforced by an AGENTS.md file in your cortex — AI agents are instructed not to 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
TUI	Terminal UI for interactive browsing

Architecture

Cerebro is a Rust workspace with four crates:

cerebro — CLI 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