Sending entire codebases to LLMs is expensive. Context windows fill with irrelevant files. Agents hallucinate when drowned in noise. You need structure. Compass builds a local code graph. It runs in Rust, so it is fast. You keep data on your machine. No code leaves your laptop. This matters for security. It also matters for cost. Cloud tokens add up. Local compute is free after hardware purchase.
This tutorial sets up Compass for an AI coding agent. You will index a repo and query it for context. Indexing 10,000 lines takes under 5 seconds on modern hardware. Query latency is under 50ms. This beats naive RAG pipelines. You get precise pointers, not raw dumps.
Setup and Indexing
- Install the CLI. Use Cargo. Run
cargo install compass. Compilation takes 2 minutes on an M1 Mac. The binary is roughly 15MB. Ensure you have Rust 1.70 or higher. - Initialize the graph. Navigate to your project root. Run
compass init. It reads your.gitignoreautomatically. It skipsnode_modulesandvendorfolders. This prevents index bloat. - Verify the index. Run
compass status. You should see file counts and node statistics. If counts are zero, check your ignore rules. Debug early to save time. - Query for context. Ask for callers of a specific function. Run
compass query --function "processPayment". The output is strict JSON. Parse this in your agent script. Handle empty results gracefully. - Inject context. Pass the returned file paths to your LLM prompt. Do not send the whole file. Send only the relevant functions. This cuts token usage by 90%. Your agent stays focused.
Common pitfalls
Ignoring vendor directories. Failing to exclude vendors bloats the graph. A node_modules folder can add millions of nodes. Your queries will slow down. Edit the config file to enforce exclusions. Check the graph size regularly.
Stale indexes. The graph does not update automatically on file save. You must re-index after major refactors. Run compass update before every agent session. This takes seconds, but forgetting it causes errors. Automate this in your pre-commit hook.
Binary compatibility. Rust builds depend on system libraries. If you move the binary to a different OS, it will fail. Build on the target machine or use static releases. Do not commit the binary to git.
Next step
Now that you have local context, build a CLI wrapper. Combine Compass with a local LLM like Llama 3. You get a fully offline coding assistant. Read our guide on [Running Local LLMs for Code Generation](https://example.com/local-llm-code) to finish the pipeline.