Installation

Installation

Columbus is a single Go binary. It is always built with -tags fts5 and CGO_ENABLED=1 (tree-sitter, SQLite, sqlite-vec and the tokenizer are C libraries).

Requirements

Requirement	Why
Go 1.26+	Build toolchain
A C compiler (cgo)	tree-sitter + SQLite/FTS5 + sqlite-vec + tokenizers
git	The only hard runtime dependency — Columbus anchors the index to git state
onnxruntime (for semantic search)	The embedding runtime; bundled in release archives, dlopen'd at runtime
ripgrep (recommended)	Search fast-path; a pure-Go fallback covers the rest
ast-grep (optional)	Optional structural matching

Semantic vs keyword builds

Natural-language search runs an on-device ONNX model (bge-small-en-v1.5). It needs two native pieces: libtokenizers.a (linked at build time) and an onnxruntime shared library (loaded at runtime). When the runtime library is missing, Columbus still works — search degrades to deterministic keyword (FTS) ranking. columbus doctor reports which mode you're in.

Option 1 — Release archive (full semantic, recommended)

Download the archive for your platform from Releases. Each archive ships the columbus binary plus the matching onnxruntime shared library beside it, so semantic search works out of the box with no network at runtime. The loader finds the lib next to the binary; override with COLUMBUS_ORT_LIB.

Option 2 — go install (keyword-fallback build)

CGO_ENABLED=1 go install -tags fts5 github.com/orafaelfragoso/columbus/cmd/columbus@latest

Installs columbus into $(go env GOPATH)/bin (put it on your PATH). This build bundles no embedding runtime: search falls back to keyword until an onnxruntime library is available (COLUMBUS_ORT_LIB or next to the binary).

Option 3 — Build from source (full semantic)

git clone https://github.com/orafaelfragoso/columbus
cd columbus
brew install zig goreleaser ripgrep ast-grep   # build/dev toolchain (macOS)
make setup        # fetch model weights + libtokenizers.a + onnxruntime into ~/.columbus/libs
make install      # -> ~/.local/bin/columbus  (override with PREFIX=/usr/local/bin)
export COLUMBUS_ORT_LIB="$HOME/.columbus/libs/libonnxruntime.dylib"  # .so on linux

make setup fetches everything the embedding engine needs; make build drops the binary in dist/columbus; make install puts it on your PATH.

Verify

columbus version
columbus doctor

doctor confirms your environment is ready — git, ripgrep, ast-grep, the embedded grammars, the vec0 extension, the onnxruntime runtime, and (inside a project) the database, index and embedding model. See Command: doctor.

[ok]   columbus     version 0.1.0
[ok]   git          /usr/bin/git
[ok]   ripgrep      /usr/bin/rg
[ok]   grammars     6 languages loaded
[ok]   vec0         sqlite-vec v0.1.6
[ok]   runtime      bge-small-en-v1.5 (384-d)
healthy

Next steps

→ Quick Start · Your First Index & Search