Skip to content

Installation

Super-Brain runs entirely on your machine. One package, one command, no accounts.

Requirements

Python

Python 3.11 or newer.

bash python --version

If you need to upgrade, we recommend uv — it installs Python and manages virtual environments in one tool.

Operating system

  • macOS 12+
  • Linux (Ubuntu 22.04+, Debian 12+, Fedora 38+, Arch)
  • Windows 10/11 (native or WSL2)

Disk space

  • Minimum: 500 MB (code graph only, no LLM)
  • Recommended: 5 GB (includes embedding model cache)
  • With local LLM: 8 GB (adds ~700 MB for Llama-3.2-1B on first use)

System dependency — FFmpeg (only if you plan to ingest audio/video)

OS Command
macOS brew install ffmpeg
Ubuntu / Debian sudo apt install ffmpeg
Fedora sudo dnf install ffmpeg
Arch sudo pacman -S ffmpeg
Windows winget install ffmpeg or choco install ffmpeg

FFmpeg is only required for ingest-audio. You can skip it if you're only ingesting code or documents.

Install Super-Brain

Option 1: pip

bash pip install agsuperbrain

bash uv add agsuperbrain

uv is faster, resolves dependencies correctly on the first try, and manages Python versions.

Option 3: From source

bash git clone https://github.com/HELLOMEDHIRA/agsuperbrain.git cd agsuperbrain pip install -e .

Use this if you want to follow main or contribute.

Verify the install

bash agsuperbrain doctor

This runs a health check on every component (graph DB, vector DB, tree-sitter parsers, embedding model, optional FFmpeg). If something is missing, doctor tells you what and how to fix it.

First-run setup

Inside any project directory:

bash agsuperbrain init

init does four things in one pass:

  1. Writes .agsuperbrain/config.yaml, .agsuperbrainignore, and updates your .gitignore.
  2. Runs ingest + index-vectors on your project. The extractor recursively walks from the project root and automatically skips .venv, node_modules, __pycache__, .git, dist, build, .tox, and other standard noise — so it works the same for flat Python, src-layout Python, Maven/Gradle/Spring Boot (src/main/java/…), Go (cmd/, internal/, pkg/), Rust crates, .NET solutions, Rails, Flutter (lib/), Swift (Sources/), Unity, Unreal, and monorepos.
  3. Starts the background file watcher so subsequent edits are incrementally re-indexed.

Overriding the defaults

bash agsuperbrain init --src ./services/api # ingest just one workspace (monorepos) agsuperbrain init --skip-ingest # only create config + start watcher

Add custom exclusions to .agsuperbrainignore or .gitignore if you want to skip additional directories (e.g., generated/, vendor/, third_party/).

Default paths

Super-Brain stores everything inside a single hidden directory:

Data Default path Configurable
Graph database (KùzuDB) ./.agsuperbrain/graph/ graph.db_path
Vector store (Qdrant) ./.agsuperbrain/qdrant/ vector.db_path
Audio cache ./.agsuperbrain/audio/ —
Config ./.agsuperbrain/config.yaml —

init adds .agsuperbrain/ to your .gitignore so nothing gets committed.

Configuration

Edit .agsuperbrain/config.yaml in your project:

```yaml

Directories to exclude from ingestion (merged with defaults like .venv, node_modules)

exclude: - third_party - generated

Languages to prioritize (leave empty for all 306)

languages: - python - typescript - go

Watcher settings

watcher: debounce_ms: 500

Storage

graph: db_path: ./.agsuperbrain/graph

vector: db_path: ./.agsuperbrain/qdrant ```

Changes apply on the next agsuperbrain command — no restart needed.

Uninstall

bash pip uninstall agsuperbrain # or: uv remove agsuperbrain

To also delete project data:

bash agsuperbrain clean # removes .agsuperbrain/ and its contents

Troubleshooting

agsuperbrain: command not found

Make sure pip's script directory is on your PATH:

```bash

macOS / Linux

export PATH="$HOME/.local/bin:$PATH" ```

On Windows:

powershell setx PATH "%PATH%;%APPDATA%\Python\Scripts"

Open a new terminal after changing PATH.

ModuleNotFoundError: No module named 'agsuperbrain'

Your virtual environment probably isn't active.

```bash

macOS / Linux

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1 ```

FFmpeg not found

Install it per the OS table above and open a new terminal so the updated PATH takes effect.

KùzuDB / Qdrant errors on first run

Run agsuperbrain clean then agsuperbrain init to rebuild. This is usually a sign that a previous run was interrupted mid-write.

Slow first query

The sentence-transformer model downloads on first use (~80 MB). Subsequent queries are instant.

Next steps