Cerebro

Cerebro is a standalone, local-first knowledge and repository intelligence platform. It combines static analysis, local RAG workflows, terminal and web interfaces, and optional vendor-specific integrations. The core runtime is designed to work without cloud credentials.

Quick Start

git clone https://github.com/marcosfpina/cerebro.git
cd cerebro

# Enter the hermetic dev shell
nix develop

# Inspect the environment
cerebro info
cerebro version

# Analyze a repository and build a local RAG index
cerebro knowledge analyze . "General Review"
cerebro rag ingest ./data/analyzed/all_artifacts.jsonl
cerebro rag query "What are the main modules in this repository?"

Prefer nix develop --command ... for one-shot execution outside an interactive shell.

Product Direction

Cerebro follows three design rules:

Standalone first: code analysis, repository metrics, local retrieval, and core UX do not require cloud access.
Cloud optional: vendor integrations are adapters, not prerequisites.
Vendor-specific by implementation: the architecture is integration-friendly, but the core does not assume a preferred cloud.

The codebase already exposes provider interfaces for language models and vector stores, which makes local and cloud-backed implementations swappable without changing the application core.

Architecture

                         +---------------------------+
                         |         Cerebro           |
                         |   CLI | TUI | Dashboard   |
                         +-------------+-------------+
                                       |
                         +-------------v-------------+
                         |        Core Services      |
                         | analysis | metrics | rag  |
                         +------+------+-------------+
                                |      |
                +---------------+      +------------------+
                |                                      |
        +-------v--------+                    +--------v---------+
        | Local Providers |                    | Optional Adapters |
        | llama.cpp       |                    | GCP integration   |
        | OpenAI-like API |                    | vendor-specific   |
        | Chroma vector   |                    | commands/providers|
        +-----------------+                    +-------------------+

Current Implementation Status

Area	Default path	Optional path	Notes
Code analysis	Tree-Sitter + Python AST	-	Local
Repository metrics	Filesystem + git scan	-	Local
LLM provider	`llama.cpp` / OpenAI-compatible	Vertex AI adapter	Adapter-based
Vector store	ChromaDB	-	Interface already exists
RAG ingestion/query	Local-first	GCP-backed workflows	Local remains primary path
Interfaces	CLI, TUI, Dashboard	-	Shared core

Interfaces

CLI

The Typer CLI is the primary operational surface:

cerebro knowledge   analyze | batch-analyze | summarize | generate-queries | index-repo
cerebro rag         ingest | query | rerank
cerebro metrics     scan | watch | report | compare | check
cerebro ops         health | status
cerebro strategy    optimize | salary | moat | trends
cerebro content     mine | analyze
cerebro test        grounded-search | grounded-gen | verify-api
cerebro gcp         burn | monitor | create-engine | status   # optional integration

TUI

nix develop --command cerebro tui

The Textual interface exposes dashboards, project views, intelligence panels, and operator flows.

Dashboard

nix develop --command cerebro dashboard

The web dashboard is backed by the FastAPI server in src/cerebro/api/server.py, while the frontend lives under dashboard/.

Core Capabilities

Static Analysis

Analyze repositories using Tree-Sitter and Python AST:

Python
JavaScript / TypeScript
Rust
Go
C / C++
Nix
Bash

Repository Intelligence

Collect zero-token operational and structural metrics:

nix develop --command cerebro metrics scan
nix develop --command cerebro metrics report .
nix develop --command cerebro metrics watch

Local-First RAG

The default RAG path stays local:

Pluggable LLMProvider
Pluggable VectorStoreProvider
ChromaDB as the current built-in vector store
llama.cpp and OpenAI-compatible endpoints as local-friendly LLM options

Optional Integrations

The repository currently ships one cloud integration track: GCP.

These commands are optional and integration-specific:

nix develop .#gcp --command cerebro gcp status
nix develop .#gcp --command cerebro gcp monitor --project <project-id>
nix develop .#gcp --command cerebro gcp burn --project <project-id> --engine <engine-id>

This integration exists beside the local core; it does not define the product.

Documentation

All project documentation lives in docs/.

Start Here

Document	Description
Documentation Hub	Overview and quick navigation
Documentation Index	Topic-based navigation
Architecture	Current architecture overview
Command Reference	CLI command usage

Selected Topics

Area	Documents
Core product	Quick Start, Cheatsheet, Keyboard Shortcuts
Architecture	Architecture Overview, Data Flow, ADR Summary
Intelligence	Capabilities, Sources, Stack Mastery
Integration-specific	GCP Credits, Automation Systems
Project planning	Master Execution Plan, Status, Coverage Gaps

Testing

# Core unit test path
nix develop --command pytest tests/ --ignore=tests/integration

# Core smoke path
nix develop --command cerebro ops health

# Optional integration tests
nix develop .#gcp --command pytest tests/integration/ -m integration

Some integration tests exercise optional external adapters and may require additional configuration.

Project Structure

src/cerebro/
  cli.py                 CLI entrypoint
  launcher.py            CLI / TUI / dashboard launcher
  api/                   FastAPI services
  commands/              Command groups
  core/
    extraction/          Repository analysis and ingestion
    rag/                 Retrieval and generation engine
    gcp/                 Optional GCP integration utilities
    utils/               Logging, resilience, helpers
  interfaces/            Provider contracts
  providers/
    chroma/              Built-in vector store provider
    llamacpp/            Local llama.cpp adapter
    openai_compatible/   OpenAI-compatible HTTP adapter
    gcp/                 Optional GCP provider adapter
  registry/              Repository discovery and indexing
  intelligence/          Intelligence domain models and workflows
  tui/                   Textual application

dashboard/               Web frontend
docs/                    Documentation
tests/                   Unit and integration tests
config/                  Project configuration

Configuration

Local-first defaults

export CEREBRO_LLM_PROVIDER="llamacpp"
export LLAMA_CPP_URL="http://localhost:8081"
export LLAMA_CPP_MODEL="current-model"

Optional OpenAI-compatible provider

export CEREBRO_LLM_PROVIDER="openai-compatible"
export OPENAI_COMPATIBLE_URL="http://localhost:8000"
export OPENAI_COMPATIBLE_MODEL="current-model"

Optional GCP adapter

export CEREBRO_LLM_PROVIDER="vertex-ai"
export GCP_PROJECT_ID="<your-gcp-project-id>"
export DATA_STORE_ID="<your-data-store-id>"

Contributing

Use the Nix environment for development and validation.
Keep the core product local-first and vendor-agnostic.
Treat cloud integrations as optional adapters.
Do not hardcode credentials, project IDs, or vendor-specific identifiers.

See docs/guides/CONTRIBUTING_DOCS.md for the current documentation workflow.

License

MIT License. See LICENSE.

Quick Start​

Product Direction​

Architecture​

Current Implementation Status​

Interfaces​

CLI​

TUI​

Dashboard​

Core Capabilities​

Static Analysis​

Repository Intelligence​

Local-First RAG​

Optional Integrations​

Documentation​

Start Here​

Selected Topics​

Testing​

Project Structure​

Configuration​

Local-first defaults​

Optional OpenAI-compatible provider​

Optional GCP adapter​

Contributing​

License​