Configuration

Configuration

Columbus is configured by one small file, .columbus.json, created by columbus install.

.columbus.json

Lives in your project root and is git-excluded (added to .git/info/exclude, so it is local-only and never committed).

{
  "schema_version": 2,
  "project_id": "proj_2fd171eebe922fad",
  "indexing": {
    "exclude": [
      "**/node_modules/**",
      "**/.git/**",
      "**/dist/**",
      "**/build/**",
      "**/vendor/**",
      "**/.next/**",
      "**/coverage/**"
    ],
    "max_file_size": 1572864
  },
  "embedding": {
    "enabled": true,
    "model": "bge-small-en-v1.5",
    "runtime": "onnx"
  },
  "output": { "color": false }
}

Field	Meaning
schema_version	Config schema version (currently 2)
project_id	Stable id; keys the database in the data dir
indexing.exclude	Glob patterns skipped during indexing
indexing.max_file_size	Files larger than this (bytes) are skipped (default ~1.5 MB)
embedding.enabled	Whether index/search attempt on-device embeddings
embedding.model	Pinned model (informational; the binary embeds one model)
embedding.runtime	Inference runtime (informational)
output.color	Enable ANSI color in text output (never in json/llm)

Missing blocks fall back to defaults, so older schema_version: 1 files keep working. Tune exclude/max_file_size (or toggle embedding.enabled), then re-run columbus reindex.

Where data lives

The database (index, graph, embedding vectors, memory, epics/stories/tasks) is not stored in your repo. It lives in your OS data directory, keyed by project_id:

OS	Path
macOS	~/Library/Application Support/columbus
Linux	$XDG_DATA_HOME/columbus or ~/.local/share/columbus
Windows	%LocalAppData%\columbus

Override the data dir

export COLUMBUS_DATA_DIR=/custom/path

COLUMBUS_DATA_DIR overrides everything (handy for tests, sandboxes, or running multiple isolated projects).

Color & environment

Color and output behavior are controlled separately — see Color & Environment.

Related

Command: install · Keeping the Index Fresh · How Columbus Works