Compass: A Local-First Code Graph Tool Built with Rust

As large language models and AI coding assistants become mainstream, a new problem has gradually surfaced: how can AI agents truly understand a large and complex codebase? Traditional text retrieval and context window stuffing approaches often fall short—they cannot accurately grasp the intricate dependency relationships between functions, classes, and modules in code. This is precisely the core problem that Compass, an open-source project that recently caught attention on Hacker News, aims to solve.

Current mainstream LLMs have context windows ranging from 4K to 128K tokens (GPT-4 Turbo supports 128K, Claude supports 200K), but even the largest context windows struggle with enterprise codebases that easily reach millions of lines. While RAG (Retrieval-Augmented Generation) technology injects relevant code snippets into prompts through vector retrieval, it's fundamentally based on text similarity search and cannot capture structural semantic relationships like call chains and inheritance hierarchies. This causes AI to frequently miss critical dependency context when handling tasks like cross-module refactoring.

Compass is a code graph tool written in Rust with a local-first design philosophy, and its positioning is very clear: it serves both human developers and AI agents.

Compass on Hacker News

What Is a Code Graph?

From Text to Structured Relationships

A code graph is a technology that parses source code into a graph structure. In this graph, nodes typically represent entities in the code (such as functions, classes, variables, modules), while edges represent relationships between them (such as calls, inheritance, references, imports).

Compared to treating code as plain text, code graphs can capture the semantic structure of code. For example, when you want to know where a particular function is called and which modules would be affected by modifying it, a graph can provide direct answers without requiring full-text search across thousands of lines of code.

Technical Foundations of Code Graph Implementation

Code graph construction typically relies on Abstract Syntax Tree (AST) parsing and semantic analysis. An AST is a tree-structured representation of source code that preserves syntactic hierarchical relationships. On top of this, symbol resolution can track definition and reference relationships of variables and functions, enabling the construction of complete Call Graphs, Dependency Graphs, and more.

The industry has already seen similar efforts—GitHub's code search uses precise parsing based on tree-sitter, and Sourcegraph's code intelligence relies on indexing protocols like SCIP (Source Code Intelligence Protocol). Compass's uniqueness lies in making this capability entirely local and explicitly targeting AI agent scenarios.

Why Code Graphs Are Especially Important for AI Agents

For AI coding assistants, the value of code graphs is even more pronounced. Current mainstream AI coding tools are limited by context windows and can often only see local snippets. Code graphs provide an efficient structured retrieval mechanism: AI agents can precisely locate relevant code along dependency relationships, obtaining the most relevant information within limited context, reducing hallucinations, and improving the accuracy of code understanding and modifications.

Compass's Core Design Philosophy

Local-First Architecture

One of Compass's most distinctive features is its "local-first" approach. This means code graph construction, storage, and querying are all completed locally on the developer's machine, with no need to upload code to the cloud.

Local-first is a software design philosophy proposed by Ink & Switch laboratory in 2019. Its core proposition is: data is primarily stored on the user's local device, software should be fully functional offline, and collaboration is achieved through peer-to-peer synchronization rather than central servers. This philosophy has gained increasing attention in the developer tools space in recent years, especially amid growing AI security and compliance pressures.

This design has several significant advantages:

Privacy and Security: Source code is one of the most critical assets for many enterprises. Local processing avoids the risk of code leaks, which is particularly crucial for teams with strict compliance requirements. Many enterprises in finance, defense, and healthcare explicitly prohibit code transmission to third-party cloud services, giving local-first AI-assisted tools a clear market opportunity.
Response Speed: Local queries require no network round trips, resulting in extremely low latency, making them suitable for real-time use as editor plugins or CLI tools.
Offline Availability: No dependency on external services means it works normally even in environments without network access.

In an era where more and more AI tools rely on cloud APIs, Compass's local-first approach offers a noteworthy differentiated choice.

Why Rust for Building Code Analysis Tools

Compass is built with Rust, a technology choice that sends a clear signal. Rust's memory safety, high performance, and garbage-collection-free characteristics make it well-suited for building system-level tools that need to handle large-scale code parsing.

In recent years, Rust has become the preferred language for building high-performance developer tools. Notable examples include the next-generation JavaScript/TypeScript bundlers SWC and Turbopack, the code linting tool oxlint (OXC project), and Python's package manager uv and code formatter Ruff. These tools typically achieve 10-100x performance improvements over their predecessors (usually written in JavaScript or Python).

Rust's Ownership System eliminates data races and memory leaks at compile time, which is particularly important for background indexing services that need to run for extended periods. For scenarios like code graphs that require fast traversal and frequent queries, Rust can deliver performance close to C/C++ while maintaining safety. Additionally, tree-sitter—an incremental parsing framework—is written in C with comprehensive Rust bindings, supporting syntax parsing for over 100 programming languages, providing a solid foundation for building multi-language code parsers.

Dual Positioning: For Humans and AI Agents

The phrasing "for humans and AI agents" in Compass's project description is worth pondering. It reveals a new trend in developer tool design: tools no longer serve only human users but must simultaneously become "infrastructure" for AI agents.

Value for Human Developers

For humans, code graphs can assist with code navigation, impact analysis, refactoring planning, and helping newcomers quickly get up to speed with unfamiliar codebases. Visualized dependency graphs are often more helpful for understanding overall system architecture than reading code line by line.

Value for AI Agents

For AI agents, Compass functions more like a "cognitive foundation layer." AI can obtain structured code context through query interfaces, enabling more reliable decisions in tasks like automated refactoring, bug fixing, and code generation.

Traditional developer tools have interaction interfaces designed for humans—GUIs, TUIs, or formatted terminal output. AI agents need structured, programmable query interfaces (typically JSON or specific protocols). This has given rise to new protocols like MCP (Model Context Protocol, proposed by Anthropic), designed to provide standardized tool invocation interfaces for AI agents. Under this paradigm, code graph tools need not only provide human-readable visualization interfaces but also expose machine-consumable APIs, allowing AI agents to autonomously perform graph traversal, path queries, and impact scope analysis.

This approach of "humans and machines sharing the same code understanding infrastructure" may become the standard paradigm for future AI-native development tools.

An Objective View: Current Status and Limitations of an Early-Stage Project

It's worth noting that based on Hacker News data, Compass is still in a very early stage—the post has only 4 upvotes and 1 comment, indicating limited community attention. This means it has not yet been validated in large-scale production environments, and its feature completeness, multi-language support scope, and actual query performance remain to be observed.

In the code understanding tool space, Compass faces competitors including: Sourcegraph (providing cross-repository code search and navigation), GitHub Code Search (precise code search based on the Blackbird engine), and various LSP (Language Server Protocol) implementations. However, most of these tools focus on human interaction or rely on cloud deployment. In the niche of local code understanding for AI agents, competition is relatively sparse. It's worth noting that AI editors like Cursor and Windsurf are also building similar code indexing capabilities internally, but typically as closed-source components not available externally.

For interested developers, at this stage it's more appropriate to evaluate Compass as a sample of a technology direction worth watching rather than immediately deploying it in production. The value of open-source projects often requires time and community collaboration to refine.

Conclusion: A Microcosm of AI-Native Development Tools

Although Compass is still a nascent project, the direction it represents is quite inspiring—local-first, high-performance, AI-agent-oriented code understanding infrastructure. As AI coding assistants evolve from "completing code" to "understanding and modifying entire codebases," how to provide AI with accurate, efficient, and privacy-respecting code context will become a critical challenge.

Regardless of whether Compass itself grows and thrives, the exploration of such tools is paving the way for software engineering in the AI era. For developers following the cutting edge of AI programming, it deserves a spot on the watch list.