Crabbuild Compass: Local-First Knowledge Graph for Code

What changed

Crabbuild has introduced Compass, a new local-first knowledge graph engine designed to process code and project artifacts. Built entirely in Rust, Compass aims to provide developers and AI coding assistants with a comprehensive, queryable map of a codebase's structure, relationships, and history. Unlike solutions that rely on cloud processing, embeddings, or vector databases, Compass operates entirely locally. It transforms source code and project files into a directed graph, enabling functionalities such as architecture mapping, dependency path tracing, and impact analysis. The engine supports deterministic, read-only queries via CompassQL, outputting results in JSON and JSONL formats. It also preserves immutable graph snapshots for specific Git commits, allowing for historical analysis and version-to-version topology diffs. Compass is designed to integrate with various tools, offering exports in formats like GraphML, SVG, Wiki, Obsidian, and Neo4j, as well as providing a VS Code extension for interactive exploration.

Installation and Initialization

Installation is available via a shell script for macOS and Linux, or a PowerShell script for Windows, pulling from the latest release. Developers can also build from source using Rust 1.97.1 or newer, or use a make install command. Once installed, compass init can be run within a project directory to create an initial graph. This command scopes the project, saves configuration to .compass/config.toml, and generates an initial output in compass-out/, including graph.json, GRAPH_REPORT.md, and orientation.json for AI assistants. Users can specify include and exclude patterns during initialization for monorepos. The compass update and compass watch commands can then be used to keep the graph current as files change, with watch running in a separate terminal.

Querying and Exploration

Compass facilitates deep code understanding through its query capabilities. Developers can ask natural language questions using compass query "your_question_here", which leverages structured discovery within the graph. The --evidence flag provides full provenance, and results are paginated with a cursor for large outputs. Specific commands like compass explain TokenVerifier and compass path ApiHandler TokenVerifier allow for detailed symbol explanations and dependency path tracing. The --affected flag, with an optional depth, can identify components impacted by a change. For visualization, compass export html generates a self-contained HTML workbench, which can be customized to include code, architecture, call, and impact graphs for specific symbols. This workbench is also accessible via the Compass VS Code extension, allowing users to navigate from graph nodes directly to source code locations.

Why it matters for builders

Compass empowers builders by providing a local, efficient, and transparent way to understand and analyze their codebases. The ability to generate detailed knowledge graphs without external dependencies or complex setups democratizes deep code inspection. This is particularly valuable for onboarding new team members, refactoring large projects, or ensuring code quality through automated structural checks. Furthermore, Compass's focus on providing precise, bounded context for AI assistants can significantly enhance the reliability and accuracy of AI-driven coding tools.

Practical impact

Developers can immediately integrate Compass into their workflow by installing the CLI and running compass init in their projects. Experimenting with compass watch can provide real-time updates as code changes. For those working with AI assistants, exploring the orientation.json and GRAPH_REPORT.md files can reveal how to leverage Compass for more focused and accurate AI interactions. The compass export html command offers a quick way to generate shareable visualizations of code architecture and dependencies.

Caveats and source limits

The source material provides comprehensive details on Compass's features, installation, and usage. However, specific performance benchmarks comparing Compass to other knowledge graph engines or code analysis tools are not presented. Information regarding pricing, licensing details beyond 'Other', or specific support tiers is also absent. The release status is indicated as 'fresh release' with a specific version compass-v0.3.13, suggesting it is an actively developed project but potentially not yet at a mature, stable release for all enterprise use cases.