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

What Compass gives you

Need	Compass capability
Understand an unfamiliar repository	Communities, architecture reports, god-node detection, and interactive HTML
Find implementation paths	Natural-language graph discovery, symbol explanations, and directed paths
Estimate change impact	Reverse dependency traversal and version-to-version topology diffs
Automate structural checks	Deterministic, read-only CompassQL with JSON and JSONL output
Ask questions about old revisions	Immutable graph realizations for exact Git commits
Give assistants focused context	Native skills, hooks, MCP serving, and compact graph queries
Connect other tools	Graph JSON, GraphML, SVG, Wiki, Obsidian, Neo4j, FalkorDB, and other exports

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.

Inspired by Graphify, extended by Compass

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. A frozen Graphify release is still used as a behavioral oracle for compatible commands, graph structures, and output contracts.

Graphify ideas and behavior
           |
           v
compatibility fixtures and differential checks
           |
           v
Compass: native Rust engine
           |
           +--> preserves proven graph workflows
           +--> adds Compass-specific capabilities
           +--> evolves independently where the products diverge

What Compass adds beyond the frozen Graphify baseline

Area	Compass extension
Runtime	One native Rust executable; Python is used only by development parity tests
Exact queries	CompassQL, a deterministic and bounded read-only openCypher subset
Versioned graphs	Immutable realizations for exact commits, historical queries, exports, and diffs
Incremental operation	Reuses compatible unchanged extraction work and atomically publishes graph plus manifest
Query safety	Explicit row, path, expansion, memory, and time limits
Native distribution	Linked parsers and native implementations for supported graph, media, database, and service boundaries

Compatibility is a foundation, not a permanent feature ceiling. Compass may diverge when native design, performance, safety, or new workflows benefit from a different contract. See Compatibility and Migration from Graphify for exact boundaries.

Performance improvements over Graphify

Compass is qualified against the frozen Python Graphify oracle on copied corpora. Results are accepted only when graph topology and read outputs match the oracle.

The current large-corpus baseline contains 850 files, 15,151 nodes, and 38,374 edges. It was recorded on an Apple M2 Max with 32 GiB RAM using five independent corpus copies.

Large-corpus case	Graphify median	Compass median	Compass speedup
Cold AST build	10.766 s	3.774 s	2.85×
Unchanged update	12.180 s	0.232 s	52.5×
One-file change	12.155 s	2.112 s	5.8×
Query	0.746 s	0.132 s	5.7×
Path	0.655 s	0.107 s	6.1×
Explain	0.609 s	0.087 s	7.0×
Affected analysis	0.250 s	0.034 s	7.4×

On the same large corpus, cold-build peak memory fell from 351.3 MiB to 291.2 MiB. The qualification gate also checks warm updates, edits, renames, deletes, query output, and memory use.

These numbers are a reproducible local baseline, not a universal promise for every repository or machine. Read Performance qualification for hardware details, raw-evidence rules, regression gates, 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

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

2. 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 automatically reuse the saved scope.

Compass writes:

compass-out/
├── graph.json        machine-readable graph
├── GRAPH_REPORT.md   architecture and community summary
├── graph.html        interactive visualization when size permits
└── manifest.json     incremental build state

3. Ask useful questions

compass query "where is authentication enforced?"
compass explain TokenVerifier
compass path ApiHandler TokenVerifier
compass affected TokenVerifier --depth 3

These commands read the saved graph and do not call a model.

Compass-specific workflows

Query exact graph patterns with CompassQL

compass query --cql \
  "MATCH (caller)-[:CALLS]->(target)
   WHERE target.label = 'authorizePayment()'
   RETURN caller.id, target.id
   LIMIT 20" \
  --format json

CompassQL is deterministic, read-only, parameterized, and resource-bounded. See the language contract and support matrix.

Travel through graph history

compass history enable --code-only
compass history build main
compass history build HEAD --profile-from main
compass query "authentication" --at HEAD~20
compass diff main HEAD

Historical builds use exact Git commits and immutable extraction fingerprints. Current and historical graphs can be queried, compared, and exported without putting generated graph data into Git. Semantic diff leads with likely breaks, behavior changes, affected callers/modules, and test evidence; use --all to expand routine symbol churn. Default text output reports any findings beyond its display budget; use --limit N to raise that budget or --all for exhaustive output.

Read the versioned history guide and storage design.

Connect a coding assistant

compass install

Inside a Git repository, Compass detects installed coding agents and configures them at the repository root. Codex, Gemini CLI, OpenCode, Copilot, and generic Agent Skills clients share one portable .agents/skills/compass package; Claude Code, Kiro, and Cline use their native skill roots. Use repeatable --platform flags when you want explicit selection:

compass install --platform codex --platform claude
compass install --all --dry-run
compass install --user --format json

The skill teaches assistants to use an existing Compass graph as the first navigation layer, request a focused subgraph, and open only the source files needed to verify an answer. Installation does not build a graph.

architecture question
        |
        v
read GRAPH_REPORT.md
        |
        v
run a focused Compass query
        |
        v
inspect the smallest useful source set

See Assistant setup for supported platforms, scope, strict mode, upgrades, and uninstall.

Inspect program behavior with evidence

Native update, extract, and watch builds also write program.json, a language-neutral Program IR containing functions, conservative basic blocks, operations, call candidates, capability coverage, provenance, and derived summaries. The offline-first pipeline combines Tree-sitter syntax evidence for Rust and TypeScript-family languages with any SCIP indexes already on disk. Compass does not invoke an indexer, compiler, language server, model, or network service to build this artifact.

Schema http://crab.build/compass/v1 reports each capability as complete, partial, indeterminate, or failed, with machine-readable reasons for every non-complete state. Unresolved calls are retained as uncertainty and are never treated as proof that no downstream target exists.

Inspect or query the current artifact without custom JSON scripts:

compass program summary
compass program coverage
compass program functions --language rust --name build
compass program show <symbol-id>
compass program callers <symbol-id>
compass program explain-call src/lib.rs:240
compass program query \
  "MATCH (f) WHERE f.kind = 'program_function' RETURN f LIMIT 20"

Supply additional offline evidence with repeatable --program-artifact path/to/index.scip options. Decoded indexes are cached by artifact digest, while freshness and normalization are invalidated per indexed document.

Structural and semantic modes

Choose the smallest mode that answers your question:

Command	Network behavior	Best for
compass update .	Local only	Normal source-code graph updates
compass extract . --code-only	Local only	Explicit no-model extraction
compass extract . --code-only --cargo	Local only	Code plus Cargo dependency edges
compass extract docs --backend …	Uses the configured provider	Semantic facts from supported documents and media

Semantic extraction is optional. Compass contacts a model provider only when you select a provider-backed workflow. Read Security and privacy before processing sensitive repositories.

Find the right document

You are…	Start here
Evaluating Compass	Getting started → How it works
Using or integrating Compass	Guides → Cookbook
Extending the Rust workspace	Architecture → Workspace tour
Looking up an interface	Commands → Outputs
Tracking future direction	Available, planned, and aspirational roadmap

The documentation hub links every concept, guide, design, implementation note, recipe, and reference.

Community and contributing

Need	Destination
Usage question or idea	GitHub Discussions
Bug or actionable feature request	GitHub Issues
Security vulnerability	Private vulnerability reporting
Code or documentation contribution	Contributing guide

Development checks, architecture boundaries, and contribution expectations are documented in CONTRIBUTING.md. Support and disclosure boundaries live in SUPPORT.md and SECURITY.md.

License

Compass's original work is dual-licensed under MIT or Apache-2.0. Third-party components retain their original licenses; see THIRD_PARTY_NOTICES.md.