Compass

A fast, local-first knowledge graph for understanding codebases.

Compass turns source code and project artifacts into a graph you can search, query, visualize, compare across Git history, and share with development tools.

large codebase
     |
     v
  Compass  ----->  architecture map
     |           \-> dependency and impact answers
     |            \-> exact CompassQL results
     |             \-> historical graph diffs
     |              \-> focused context for assistants
     v
less searching, smaller context, traceable evidence

Get started · Read the documentation · Explore the roadmap · View releases

Use Compass inside your editor with the first-party Compass Codegraph extension for VS Code. See the VS Code extension guide for current graphs, cursor-rooted call graphs, architecture flow, queries, and exact Git evolution.

Put Compass in your daily loop

Use Compass first as a local context layer for coding assistants. Build the graph, install the agent integration, and keep the graph synchronized while you work:

compass init
compass install
compass watch

Run compass watch in a second terminal. For a focused task, an installed assistant starts with compass query "<question>". On a first session or broad repository orientation, it reads only the bounded Agent Orientation at the start of compass-out/GRAPH_REPORT.md, then runs a focused query. It checks direction, ambiguity, completeness, truncation, and pagination before opening only the cited source needed to verify its answer.

Inside a Git repository, compass install detects supported assistants and always includes the portable Agent Skills integration. Confirm that the intended host appears under Selected. If it does not, select one or more platforms explicitly:

compass install --platform codex
compass install --platform codex --platform claude
compass install --all --dry-run

See Connect a coding assistant for supported agents, explicit platform selection, upgrades, and uninstall.

Review the graph yourself

Human graph exploration is optional. Run compass export html, or choose Open Code Graph in VS Code, when you want to inspect the architecture directly:

Start at the package map, filter by subsystem, then select any node to inspect its dependencies and source.

compass export html

# Put several perspectives in one self-contained page.
compass export html \
  --code-graph \
  --architecture-graph \
  --call-graph checkout \
  --impact-graph checkout

Refresh the browser after a build, or reopen the graph in VS Code.

The exported page and VS Code graph use the same workbench shell. Switch among requested code, call, impact, affected, architecture, history, and artifact lenses without losing the snapshot context. Use the graph from the right sidebar:

1. Search for a symbol or file.
2. Select a node to inspect its source, signature, community, evidence, and relationships.
3. Open the source card, or double-click a located node, to jump to the exact code.
4. Filter communities or change the layout when you need a different level of detail.

The graph toolbar includes an exploration panel for isolating a selected 1–4-hop neighborhood, following incoming, outgoing, or both edge directions, adjusting layout spacing, and showing a navigable minimap. Press ? in the graph to see camera and exploration keyboard shortcuts.

Right-click inside a function in VS Code to open callers, callees, impact, related symbols, or a path.

What Compass gives you

Structural extraction and graph queries run locally. They do not require Python, embeddings, a vector database, model credentials, or runtime parser downloads.

How it works

Compass discovers project files, extracts entities and relationships, resolves cross-file references, analyzes the resulting graph, and publishes one consistent snapshot.

function / class / file / document / schema object       node
CALLS / IMPORTS_FROM / USES / CONTAINS                   relationship
dense group of related nodes                             community
direct / resolved / uncertain evidence                   provenance

Relationships retain their direction, source location, and provenance:

CheckoutHandler
    |
    +-- CALLS [EXTRACTED] --> authorizePayment()
    |                              |
    |                              +-- USES --> PaymentGateway
    |
    +-- CALLS [INFERRED]  --> reserveInventory()

Read How Compass works for the complete pipeline and Graph model for the data model.

Project lineage

Compass is inspired by and modeled after Graphify. Graphify established the core workflow: extract a codebase into a knowledge graph, analyze its communities, and use focused graph queries to navigate complex projects.

Compass gives explicit credit to that foundation, but it is now an independent product with its own implementation, commands, configuration, artifacts, and test suite. Compass does not execute or depend on Graphify.

Compass capabilities

See Compatibility for Compass-owned contracts and Migration from Graphify for the one-time hard cutover.

Performance

Compass performance is qualified against Compass-owned baselines while preserving graph correctness and deterministic output. Read Performance qualification for the evidence policy and benchmark commands.

Quick start

1. Install

On macOS or Linux (Apple Silicon/ARM64 or Intel/AMD64):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/crabbuild/compass/releases/latest/download/install.sh | sh

On Windows x64 or ARM64, run the checksum-verifying PowerShell installer:

irm https://github.com/crabbuild/compass/releases/latest/download/install.ps1 | iex

For an offline install, download the matching archive and .sha256 file from the latest release, verify the checksum, extract it, and add the directory containing compass.exe to PATH.

Or build from source with the pinned Rust 1.97.1+ toolchain:

git clone https://github.com/crabbuild/compass.git
cd compass
make install

make install uses an existing ~/.cargo/bin, otherwise it creates and uses ~/.local/bin. To choose another location, run make install BINDIR="$HOME/bin".

You can also install directly through Cargo:

cargo install --locked --path crates/compass-cli --bin compass

Upgrade any installed Compass executable to the latest stable release with:

compass upgrade

Compass reads a bounded static release manifest, verifies the selected archive's size and SHA-256 digest, and checks the staged executable's version before replacing the running executable. The upgrade path does not use the rate-limited GitHub REST API. If no newer release is available, it exits successfully and reports that the installed version is already the latest.

2. Install the VS Code extension (optional)

After installing the Compass CLI, install Compass Codegraph from the VS Code Marketplace by selecting Install on its Marketplace page. You can also install it from a terminal:

code --install-extension crabbuild.crabbuild-compass-vscode

Open your repository in VS Code. The extension detects the installed Compass CLI and guides you to initialize the repository from the Compass sidebar.

3. Initialize and build a local graph

cd your-project
compass init

compass init previews the eligible corpus, saves project scope in .compass/config.toml, and performs the first structural build. For automation or a focused monorepo scope:

compass init . --include src --include 'services/*/src' --exclude '**/generated/**' --yes

After setup, compass update and compass watch