Skip to content

Contributor Quickstart

The main setup path for contributors working from a user-owned local checkout. Brings up a working dev environment, validates the CLI and state layout, and runs the project quality gate.

Don't clone into /opt for development

On macOS and many Linux systems /opt is root-owned, which forces sudo into ordinary edit, install, and test commands. Use a directory you own — ~/Code/SecondBrain, ~/src/SecondBrain, or similar.

Prerequisites

  • Python 3.12 or 3.13 (pinned >=3.12,<3.14 in pyproject.toml)
  • A local checkout of the repo
  • Virtualenv support
  • Optional: provider keys for live LLM-backed flows

1. Install

mkdir -p ~/Code
cd ~/Code
git clone https://github.com/contextosai/SecondBrain.git
cd SecondBrain

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"

Use a directory you own, such as ~/Code/SecondBrain, ~/src/SecondBrain, or another workspace under your home directory. Avoid cloning into /opt for normal development: on macOS and many Linux systems /opt is root-owned, which can force sudo into ordinary edit, install, and test commands.

If your default python3 is outside 3.12 / 3.13, create the virtualenv with a supported binary, for example python3.12 -m venv .venv, or use the repo setup target with make setup PYTHON_BIN=/path/to/python3.12. make setup auto-detects python3.12/python3.13 on PATH ahead of plain python3, which on Homebrew often resolves to 3.14.

After activation, run Python commands through the virtualenv. If your shell does not expose a bare python, use .venv/bin/python directly, for example .venv/bin/python -m pytest -q.

Use sb as the primary entrypoint after the editable install. The wrapper script ./scripts/sb is still available when you explicitly need it.

2. Run First-Time Setup

sb onboard
sb doctor
make help

sb onboard is the guided first-run path. It persists local defaults, can build promoted knowledge, and can optionally build the offline context index. sb doctor checks the environment and suggests next commands based on the current state.

Useful help pages:

sb --help
sb onboard --help
sb doctor --help
sb chat --help
sb dev review --help

3. Build A Minimal Working Loop

sb ingest vault/
sb context index
sb ask "What changed this week?"

That validates ingest, retrieval, and the optional offline index on a local checkout.

About the state/ directory

After your first ingest or query, you'll see a state/ directory appear at the repo root (and possibly brain/state/ for legacy installs). This is local runtime data — vector indexes, sqlite databases, ingest artifacts, generated fixtures — and it is gitignored on purpose. It is regenerated per-machine from your vault and config; it is not, and should not be, shared in git.

If a teammate sees their checkout missing state/, that is the expected empty state. They populate it by running sb ingest, sb context index, or sb onboard locally. SecondBrain auto-creates the directory layout the first time it needs it, and auto-migrates legacy state/chroma/ data into state/retrieval/ on the first run with the default LanceDB backend.

Run sb memory migrate --from chroma --to lancedb to trigger that migration explicitly, or sb doctor to inspect the current backend and storage layout.

4. Run The Contributor Quality Gate

sb dev review

This is the preferred pre-PR command. It runs the project formatting, linting, type-check, and test steps in one place.

Lower-level commands are still useful when you want a narrower loop:

ruff check .
pytest -q
make docs
sb quality harness audit --changed-only --json

For component-specific loops, use component-test-entrypoints.md. Prefer the smallest loop that covers the source area you changed, then broaden only when the change crosses a runtime, UI, or docs boundary.

For agent-directed work, use agent-operability.md to choose the task template, autonomy level, and failure-promotion path before expanding scope.

If You Already Cloned Into /opt

If your checkout is root-owned under /opt, prefer moving it into a user-owned workspace:

mkdir -p ~/Code
sudo mv /opt/SecondBrain ~/Code/SecondBrain
sudo chown -R "$USER":"$(id -gn)" ~/Code/SecondBrain
cd ~/Code/SecondBrain

If you intentionally keep that checkout under /opt, take ownership of only the repo checkout, not the whole /opt tree:

sudo chown -R "$USER":"$(id -gn)" /opt/SecondBrain

5. Doc-specific validation

When you change docs (or anything that touches the CLI, providers, or decision namespaces), verify the auto-gen reference pages stay in sync:

make docs-check

This runs sb docs check (diffs every auto-generated reference page against the live registries) and mkdocs build --strict (no broken links or stale nav references). Both gates run on every PR in CI.

If sb docs check fails, regenerate:

sb ui-schema --write-default      # only after CLI surface changes
make docs-reference               # writes cli.md, providers.md, decisions.md, pages-index.md

For local browser preview:

make docs-serve

What make docs-reference regenerates

  • docs/reference/cli.md — from brain/ui_schema/cli_schema.json
  • docs/reference/providers.md — from brain.providers.provider_registry
  • docs/reference/decisions.md — from brain.decisions.namespace
  • docs/pages-index.md — alphabetical index of every doc page

The skills reference (docs/reference/skills.md) is regenerated separately via sb skills docs-write.

Next reads