Compass
Use cases

Turn uncertainty into a smaller question.

Compass gives each kind of repository uncertainty a practical surface: orient in the graph, trace impact, focus a tool, or compare how the system evolved.

Install Compass

Developer workflows

Start from the work, not the feature list.

Choose the question that is blocking the next decision. The workflow pages are now one connected guide, so you can move between them without resetting context.

ExploreRead an unfamiliar codebaseFind communities, entry points, and surprising connections before you start editing.ImpactEstimate change blast radiusTraverse incoming relationships from a changed symbol and keep the path evidence attached.AssistGive tools focused contextReturn compact graph answers to assistants, editors, and automation instead of a context dump.HistoryUnderstand evolutionCompare graph realizations across exact revisions when a source diff hides the topology.

Explore

Build a mental model before you build a plan.

Exploration is not about reading every file. It is about choosing a small, defensible path through the system and knowing where that path came from.

Edge anatomy

A relationship is useful when it can answer follow-up questions.

Compass / visual contract
A Compass relationship with evidenceA directed calls edge connects two symbols and retains its relation, confidence, source range, and provenance.callertargetCALLS · directsource anchorsrc/checkout.rs:42provenanceextracted · parser evidencerelationship siteline 42 → line 88
Leave with more than a picture.
A shortlist of meaningful entry points.A path you can explain to a teammate.Source anchors for the next edit.A repeatable question for the next session.
OpenLoad the local graph and scan communities.
HoverInspect node identity, path, and kind.
TraceFollow one directed edge into the code.
RecordSave the query and source anchors.

Impact

See what a change can reach before it reaches production.

Start at a symbol, walk directed incoming relationships, and keep the evidence for every affected target in view. A useful blast radius is bounded and explainable.

Bounded traversal

Start at the changed symbol; keep the path visible.

Compass / visual contract
Compass impact pathA changed payment function is traversed through three directly connected symbols. Each node keeps its source path and the traversal stays within explicit depth and result limits.CALLSCALLSCALLSCHANGED SYMBOLcharge()src/payments.rs:42TARGET 01authorize()src/gateway.rs:88TARGET 02CheckoutHandlersrc/checkout.rs:17TARGET 03write_receipt()src/receipt.rs:61direction: changed → affected · depth 1..3 · max 100 results · anchors retained
Start
Exact symbol, path, or node id.

Kept explicit in the query result.

Direction
Incoming relationships for reachability.

Kept explicit in the query result.

Bounds
Depth, fan-out, and result limits.

Kept explicit in the query result.

Evidence
Edge type, anchor, and provenance.

Kept explicit in the query result.

A reviewable blast radius

Separate reachable from merely possible.

Keep the graph result next to the diff. Reviewers can inspect the edge, jump to the source range, and decide whether the path is actionable.

impact.json

path: payments.rs → Gateway → Checkout

edge: CALLS · direct · line 42

bound: depth 1..3 · limit 100

status: reviewable · provenance retained

Assist

Give assistants a map, not a context dump.

Expose focused graph queries through native skills, hooks, MCP, and editor workflows so tools can ask smaller, better-scoped questions.

Focused context

One question in, one bounded answer out.

Compass / visual contract
Compass assistant context flowA local repository is queried through CompassQL and returns a compact answer with identity, path, and provenance.Repositorylocal files + graphCompassQLbounded read-only queryAnswerpath + evidenceno context dumpmachine-readableidentity · direction · bounds · provenance
handoff

Ask

Resolve the user’s question into a path, impact, or relationship query.

handoff

Bound

Apply explicit depth, limit, and provider boundaries before execution.

handoff

Return

Keep identities, anchors, diagnostics, and provenance in the answer.

assistant-context.json

question: what calls CheckoutHandler?

paths: 3 · depth: 1..4

answer: PaymentGateway, Inventory.reserve

evidence: source anchors + direct edges

Integration choices

Fit the boundary to the tool.

Use the CLI in scripts, MCP for a local tool boundary, native skills for repeatable workflows, or the shared viewer when a human needs to inspect the answer.

CLIMCPVS CodeJSONL

History

Understand how the system evolved, not just what the diff touched.

When a source diff is too narrow, compare the realizations that produced the system before and after the change. Published snapshots stay immutable.

Graph A → Graph B

Two code graphs. One explicit comparison.

Compass / visual contract
A

Graph A

Baseline

immutable

Exact commit

a83f2c

4 nodes
3 relationships

Graph A at commit a83f2cThe baseline graph has four nodes and three relationships.
B

Graph B

Current

immutable

Exact commit

f0b219

4 nodes
4 relationships

Graph B at commit f0b219The current graph has four nodes, four relationships, one added relationship, and one changed node.ADDED RELATIONSHIPCHANGED NODE
A · a83f2cB · f0b219

Exact graph identities stay attached

1 relationship added1 node changedsource evidence retained
CommitBind the question to an exact revision.
CompareDiff graph structure and source evidence.
PreserveKeep historical answers stable and reviewable.

Start with the uncertainty

Give the codebase a bearing.

Install Compass locally, choose one question, and keep the path from answer back to source.

Install Compass See the product