Code Compass 🧭
Local-First Agent Knowledge Framework & Local MCP Server for Software Repositories
Table of Contents
- Product Vision & Philosophy
- Architecture Overview
- Prerequisites & Installation
- Quick Start Tutorial
- CLI Command Reference
- Configuration Reference (
compass.yaml) - Knowledge Repository Specification
- Knowledge Models & Provenance
- Connecting AI Coding Agents (MCP Server Integration)
- MCP Tools Reference & Examples
- Extending Code Compass
- Testing & Verification
- Privacy & Security Guarantee
- Roadmap
- License
🌟 Product Vision & Philosophy
AI coding agents (such as Claude, Cursor, Cline, and Copilot) have access to individual source files, but they fundamentally lack a persistent, structured map of the overall repository. When faced with large codebases, agents:
- Waste valuable context window tokens performing brute-force text searches.
- Miss critical architectural boundaries and module dependencies.
- Fail to calculate the true blast radius / change surface of proposed modifications.
- Hallucinate relationships between components.
Code Compass solves this by generating an explicit, deterministic knowledge layer and serving it directly to agents over the Model Context Protocol (MCP).
Core Principles
- Local-First & Private: No hosted API, no telemetry, no cloud backend, no phone-home mechanism. Everything runs locally on your machine.
- Deterministic Facts First: Distinguishes verified facts extracted from AST/code analysis from probabilistic LLM interpretations.
- Human-Readable Knowledge: Knowledge is persisted as clean Markdown, YAML, and JSON files that developers can inspect, version control with Git, and edit.
- MCP as an Interface: The MCP server is a thin access layer over the knowledge graph, not a proprietary database.
🏛 Architecture Overview
┌────────────────────────────────────────────────────────┐
│ Local Source Repository │
│ (Python, Modules, Git History) │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Code Compass CLI │
│ │
│ ┌──────────────────┐ ┌─────────────────────┐ │
│ │ Repository │ │ Python AST │ │
│ │ Scanner ├────────►│ Analyzer │ │
│ └──────────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌──────────────────┐ ┌──────────▼──────────┐ │
│ │ Git History │ │ NetworkX Knowledge │ │
│ │ Extractor ├────────►│ Graph Engine │ │
│ └──────────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Knowledge Writer │ │
│ └─────────────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Local Knowledge Repository │
│ │
│ ├── manifest.yaml (Project meta & stats) │
│ ├── architecture/ │
│ │ └── overview.md (Deterministic overview) │
│ ├── components/ │
│ │ └── components.json (Symbols, signatures) │
│ ├── graph/ │
│ │ └── graph.json (Nodes & relationships) │
│ ├── conventions/ (Coding rules) │
│ ├── workflows/ (Dev guides) │
│ ├── decisions/ (ADRs) │
│ └── metadata/ │
│ └── build.json (Timestamps & Git stats) │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Local MCP Server (FastMCP) │
│ (stdio transport) │
│ │
│ • search_knowledge • get_dependencies │
│ • get_project_overview • get_file_context │
│ • get_component • get_change_surface │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ AI Coding Agents │
│ (Claude Desktop, Cursor, Cline, Continue, Zed) │
└────────────────────────────────────────────────────────┘
📦 Prerequisites & Installation
Prerequisites
- Python: Version 3.12 or newer
- Git: Optional (used for extracting commit metadata and change history)
Install from PyPI
Once published, install the CLI into an isolated tool environment:
pipx install code-compass-knowledge
# or, with uv:
uv tool install code-compass-knowledge
Then run it from the repository you want to index:
cd /path/to/your/repository
compass init --name my-app --source . --knowledge ./knowledge --non-interactive
compass build --config compass.yaml
compass doctor --config compass.yaml
The code-compass-knowledge package includes a local stdio MCP server. Add compass serve --config /absolute/path/to/compass.yaml to your MCP host; the host provides its own AI model. No Code Compass cloud service or separate agent account is needed. For a temporary run without installing a global command, use uvx --from code-compass-knowledge compass ....
To publish a release, configure PyPI Trusted Publishing for this GitHub repository and the pypi environment, then push a version tag such as v0.1.0. The workflow builds the wheel and source archive and publishes them without a long-lived PyPI token. Keep the tag version aligned with project.version in pyproject.toml.
Install from source (development)
# 1. Clone your project or navigate to code-compass
cd code-compass
# 2. Create and activate a Python virtual environment
python -m venv .venv
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Linux / macOS:
source .venv/bin/activate
# 3. Install in editable mode with development dependencies:
pip install -e ".[dev]"
Alternatively, install runtime dependencies using requirements.txt:
pip install -r requirements.txt
🚀 Quick Start Tutorial
Follow these steps to analyze a repository and connect an AI agent in under 2 minutes:
Step 1: Initialize Configuration
Run compass init to generate a compass.yaml file:
compass init --name my-app --source . --knowledge ./knowledge
Step 2: Check System Health
Run compass doctor to verify that Python, Git, and directories are properly configured:
compass doctor --config compass.yaml
Step 3: Analyze the Codebase
Inspect your repository without writing anything to disk:
compass analyze --config compass.yaml
Step 4: Build the Knowledge Repository
Generate the full knowledge repository on disk:
compass build --config compass.yaml
Step 5: Start the MCP Server
Launch the MCP server to serve the generated knowledge to coding agents:
compass serve --config compass.yaml
💻 CLI Command Reference
1. compass init
Creates a starter configuration file (compass.yaml).
compass init [OPTIONS]
Options:
--name,-n: Project name (defaults to current directory name).--source,-s: Path to the source code repository (default:.).--knowledge,-k: Destination directory for the knowledge repository (default:./knowledge).--language,-l: Primary language to analyze (default:python).--output,-o: Config filename (default:compass.yaml).--non-interactive: Run in batch mode without interactive prompts.
2. compass doctor
Runs a diagnostic health check on your environment.
compass doctor --config compass.yaml
Checks Performed:
- Python runtime version (3.12+ required).
- Git CLI executable availability.
- Configuration file syntax and validity.
- Source repository path existence.
- LLM Privacy Mode verification (confirms offline status).
3. compass analyze
Performs an in-memory scan and AST analysis of the repository and prints a summary.
compass analyze [--config compass.yaml] [--verbose]
Sample Output:
Code Compass Analysis
Project: my-project
Files analyzed: 147
Python files: 112
Classes: 86
Functions/Methods: 431
Imports & Dependencies: 624
External Packages: 14
Git commits analyzed: 100
Knowledge graph:
Nodes: 517
Relationships: 843
4. compass build
Analyzes the codebase and writes the complete standalone knowledge repository to the directory configured in knowledge.path.
compass build [--config compass.yaml] [--verbose]
5. compass serve
Launches the local Model Context Protocol (MCP) server over stdio. If the knowledge repository has not been generated yet, it automatically builds it first.
compass serve [--config compass.yaml]
6. compass commit
Stages and commits changes in the local knowledge repository using Git on demand.
compass commit [--message "docs(knowledge): update architectural notes"] [--config compass.yaml]
⚙️ Configuration Reference (compass.yaml)
# ====================================================================
# Code Compass Configuration File
# ====================================================================
# Project Metadata
project:
name: "my-project"
description: "Core backend service for authentication and payments"
version: "0.1.0"
# Source Code Repository Configuration
source:
path: "."
ignore_patterns:
- ".git"
- "node_modules"
- ".venv"
- "venv"
- "__pycache__"
- "dist"
- "build"
- "coverage"
- ".env"
- ".pytest_cache"
- "*.egg-info"
# Knowledge Repository Destination
knowledge:
path: "./knowledge"
# Analysis Engine Flags
analysis:
languages:
- python
files: true # File structure & role classification
imports: true # Import resolution & stdlib/external classification
symbols: true # Class, function, parameter & AST analysis
git_history: true # Git commit metadata & file modification analysis
max_git_commits: 100 # Max commits to extract
Note on AI Overviews: Code Compass does not require any external LLM API keys or configurations. When you build the repository, Code Compass deterministically maps the architecture. Your active AI coding agent (Claude, Cursor, Antigravity, etc.) can directly supply and enrich the executive AI overview using the
update_overviewMCP tool!
📂 Knowledge Repository Specification
When compass build runs, it generates the following directory structure:
knowledge/
├── manifest.yaml
├── architecture/
│ └── overview.md
├── components/
│ └── components.json
├── conventions/
│ └── README.md
├── workflows/
│ └── README.md
├── decisions/
│ └── README.md
├── files/
│ └── src/
│ └── app.py.md
├── graph/
│ └── graph.json
└── metadata/
└── build.json
File Breakdown
manifest.yaml: Contains metadata, generator version, scan statistics, and detected languages.architecture/overview.md: A deterministic Markdown overview detailing:- Top-level folder structure
- Discovered internal modules
- External package dependencies
- Inter-module relationship map (
module_a → module_b) - Curated executive overview supplied by the AI agent
components/components.json: An array of discovered classes, functions, and modules, complete with docstrings, signatures, and line-level source provenance.files/: Mirrored per-file Markdown documentation containing AST symbol breakdowns and space for curated file gotchas/notes.graph/graph.json: The complete NetworkX knowledge graph serialized into JSON (nodesandedges).conventions/,workflows/,decisions/: Human and agent-maintainable folders for coding rules, runbooks, and Architecture Decision Records (ADRs).metadata/build.json: Build timestamps, scan metrics, and Git commit summaries.
🧠 Knowledge Models & Provenance
Every node and relationship in the knowledge graph includes explicit metadata and provenance:
Node Types
Project: The root software repository.File: A physical file on disk (size, line count, language).Module: A logical code module.Class: Class definition, docstring, base classes, decorators.Function/Method: Function definition, signature, parameters, return type, docstring.ExternalDependency: Third-party package (e.g.pydantic,fastapi).GitCommit: Commit hash, author, date, message.
Relationship Types
CONTAINS: Structural hierarchy (Project CONTAINS File,Module CONTAINS Class).IMPORTS: Import dependency (Module IMPORTS Module).CALLS: Function invocation (Function CALLS Function).INHERITS: Class inheritance (Class INHERITS Class).DEPENDS_ON: Dependency on external package (Module DEPENDS_ON ExternalDependency).MODIFIED_BY: File change history (File MODIFIED_BY GitCommit).
Provenance Example
{
"id": "class:src/services.UserService",
"type": "class",
"name": "UserService",
"is_deterministic": true,
"source": {
"file": "src/services.py",
"line_start": 12,
"line_end": 45,
"method": "ast"
},
"docstring": "Service handling user business logic."
}
🔌 Connecting AI Coding Agents (MCP Server Integration)
Code Compass provides a standard Model Context Protocol (MCP) server communicating over stdio. Code Compass supplies deterministic tools and local knowledge; the user's selected MCP host supplies the model and agent behavior. Install Code Compass with pipx or uv tool, then configure the host to run compass serve with an absolute path to the project's compass.yaml and restart the host.
1. Claude Desktop
Add Code Compass to your claude_desktop_config.json:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"code-compass": {
"command": "compass",
"args": ["serve", "--config", "C:/path/to/your/project/compass.yaml"]
}
}
}
2. Cursor IDE
In Cursor settings or .cursor/mcp.json:
{
"mcpServers": {
"code-compass": {
"command": "compass",
"args": ["serve", "--config", "./compass.yaml"]
}
}
}
3. Cline / Roo-Code
Add to cline_mcp_settings.json:
{
"mcpServers": {
"code-compass": {
"command": "compass",
"args": ["serve", "--config", "compass.yaml"],
"disabled": false,
"autoApprove": [
"get_project_overview",
"search_knowledge",
"get_component",
"get_dependencies",
"get_file_context",
"get_change_surface"
]
}
}
}
4. Continue.dev
In ~/.continue/config.json:
{
"mcpServers": [
{
"name": "code-compass",
"command": "compass",
"args": ["serve", "--config", "compass.yaml"]
}
]
}
5. Windsurf & Zed
Set the executable command to compass with arguments ["serve", "--config", "compass.yaml"].
🛠 MCP Tools Reference & Examples
When connected via MCP, the AI agent has access to 9 specialized tools:
The query tools only read generated knowledge. update_knowledge and update_overview write to the configured knowledge directory; commit_knowledge stages and commits changes there when called. In clients that support tool approval controls, leave write tools unapproved for automatic execution unless you explicitly want that behavior.
| Tool | Parameters | Description |
|---|---|---|
get_project_overview |
None | Returns the high-level architecture overview markdown. |
search_knowledge |
query: str |
Searches symbols, classes, functions, docstrings, and curated markdown documents. |
get_component |
name: str |
Retrieves full signature, docstring, source provenance, and metadata for a component. |
get_dependencies |
name: str |
Returns upstream dependencies and downstream dependents for a component. |
get_file_context |
path: str |
Returns all symbols, containment relationships, and metadata for a source file. |
get_change_surface |
component: str |
Calculates the blast radius / impacted nodes in the knowledge graph. |
update_knowledge |
category: str, title: str, content: str |
Allows the AI agent to save new rules, conventions, workflows, ADRs, findings, or file notes directly into the knowledge repository. |
update_overview |
summary: str |
Allows the active AI agent to generate or update the executive AI overview section in architecture/overview.md. |
commit_knowledge |
message: Optional[str] |
Commits modified knowledge files to the knowledge repository Git history on user demand. |
Example Agent Interactions
1. Exploring Architecture
User Prompt: "Give me an overview of how authentication is structured in this repository."
Agent Action: Callsget_project_overview()followed byget_component("AuthService").
2. Planning Refactors & Blast Radius
User Prompt: "I want to modify the
UserRepositoryinterface. What other components will be impacted?"
Agent Action: Callsget_change_surface("UserRepository")to receive the exact list of dependent services.
3. Updating Knowledge When Finding a Gap or Rule
User Prompt: "You shouldn't query the SQL session inside route handlers; always use the Service layer. Record this in Code Compass so we don't repeat this."
Agent Action: Callsupdate_knowledge(category="conventions", title="router-database-boundary", content="Never query DB sessions directly inside route handlers. Route handlers must only call Service classes.").
4. Persisting File-Level Insights & Gotchas
User Prompt: "Make note of the thread-safety caveat in payment processor."
Agent Action: Callsupdate_knowledge(category="files", title="src/payment.ts", content="Caution: concurrent calls to processPayment must acquire the mutex lock.").
🔧 Extending Code Compass
Adding a New Language Analyzer
Create a class inheriting from BaseAnalyzer:
from pathlib import Path
from typing import Optional
from compass.analyzers.base import BaseAnalyzer, AnalysisResult
class KotlinAnalyzer(BaseAnalyzer):
def can_analyze(self, file_path: Path | str, language: Optional[str] = None) -> bool:
return Path(file_path).suffix == ".kt"
def analyze_file(self, file_path: Path, relative_path: str) -> AnalysisResult:
# Parse AST and return AnalysisResult
...
Agent-Driven Knowledge Curation
Code Compass is 100% deterministic and local-first. It does not require or make calls to external LLM APIs. Instead, your active chat agent (e.g. Claude, Cursor, Antigravity, Cline) performs architectural analysis directly, persisting learnings and Architecture Decision Records (ADRs) through the update_knowledge and update_overview MCP tools.
🧪 Testing & Verification
Code Compass includes a comprehensive unit and integration test suite:
# Run all tests
pytest
# Run tests with verbose output
pytest -v
Test Coverage Highlights
- Repository Scanner Tests: Validates file discovery, language classification, and ignore rules.
- Python Analyzer Tests: Validates AST symbol extraction, classes, functions, decorators, calls, and imports.
- Tree-sitter Multi-Language Tests: Validates AST symbol, import, inheritance, and call graph extraction across TypeScript, JavaScript, Go, Rust, Java, and C/C++.
- Knowledge Graph Tests: Validates NetworkX node/edge operations, queries, serialization, and blast radius calculation.
- Knowledge Writer Tests: Validates deterministic markdown generation, template seeding, and JSON schemas.
- Agent Curation & Privacy Tests: Verifies zero external LLM API dependencies and tests active AI agent curation tools.
- MCP Server & Tool Integration: Tests end-to-end knowledge querying via MCP tools.
🔒 Privacy & Security Guarantee
Code Compass is strictly local-first. The Code Compass project does not receive, store, transmit, or process your source code.
- No Remote Telemetry: Zero analytics, zero logging to external servers.
- Zero Cloud Infrastructure: No proprietary cloud backend or hosted database.
- Deterministic Offline Analysis: All AST and graph analysis runs entirely on your local CPU.
- 100% Local & Private: No external LLM keys or cloud API calls. Your active coding assistant interacts directly with the local MCP server over stdio.
🗺 Roadmap
- Tree-sitter multi-language integration (TypeScript, JavaScript, Go, Rust, Java, Ruby, C/C++).
- Local vector embedding and semantic search over docstrings and code context.
- Automated Architecture Decision Record (ADR) generation.
- Architecture rule validation & linting (e.g., preventing illegal layer imports).
- Incremental file-watching synchronization daemon.
- Pre-commit hooks & GitHub Actions for automated knowledge repository updates.
📄 License
This project is licensed under the MIT License.
Metadata
Release files for code-compass-knowledge 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| code_compass_knowledge-0.1.0.tar.gz | 50.4 kB | With provenance | Details for code_compass_knowledge-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| code_compass_knowledge-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for code_compass_knowledge-0.1.0-py3-none-any.whl |
Total release size: 101.9 kB
Release files / code_compass_knowledge-0.1.0.tar.gz
| Download URL | code_compass_knowledge-0.1.0.tar.gz |
|---|---|
| Size | 50.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
83dc584abf6b09a2f86d5ebe2e33ac74fdcd6aff97ea3d7eb923f71b51245b85
|
|
BLAKE2b-256 checksum How to use checksums |
c2723be7d866ce814125a30a1d513e6f92224e140929fab4f67da855f6178e36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / code_compass_knowledge-0.1.0-py3-none-any.whl
| Download URL | code_compass_knowledge-0.1.0-py3-none-any.whl |
|---|---|
| Size | 51.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
083558a57d011e0c321c92925d10a663ff0281a1fd4386517286f50254272b12
|
|
BLAKE2b-256 checksum How to use checksums |
5bc7e0fade107f2d8fd66180933c6c6106f371b2a8a3a240a478ef6b6c2a284f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for code-compass-knowledge 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for code_compass_knowledge-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.