Skip to main content

Code Compass 🧭

Local-First Agent Knowledge Framework & Local MCP Server for Software Repositories

License: MIT Python: 3.12+ MCP Privacy: 100% Local


Table of Contents

  1. Product Vision & Philosophy
  2. Architecture Overview
  3. Prerequisites & Installation
  4. Quick Start Tutorial
  5. CLI Command Reference
  6. Configuration Reference (compass.yaml)
  7. Knowledge Repository Specification
  8. Knowledge Models & Provenance
  9. Connecting AI Coding Agents (MCP Server Integration)
  10. MCP Tools Reference & Examples
  11. Extending Code Compass
  12. Testing & Verification
  13. Privacy & Security Guarantee
  14. Roadmap
  15. 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

  1. Local-First & Private: No hosted API, no telemetry, no cloud backend, no phone-home mechanism. Everything runs locally on your machine.
  2. Deterministic Facts First: Distinguishes verified facts extracted from AST/code analysis from probabilistic LLM interpretations.
  3. Human-Readable Knowledge: Knowledge is persisted as clean Markdown, YAML, and JSON files that developers can inspect, version control with Git, and edit.
  4. 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_overview MCP 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

  1. manifest.yaml: Contains metadata, generator version, scan statistics, and detected languages.
  2. 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
  3. components/components.json: An array of discovered classes, functions, and modules, complete with docstrings, signatures, and line-level source provenance.
  4. files/: Mirrored per-file Markdown documentation containing AST symbol breakdowns and space for curated file gotchas/notes.
  5. graph/graph.json: The complete NetworkX knowledge graph serialized into JSON (nodes and edges).
  6. conventions/, workflows/, decisions/: Human and agent-maintainable folders for coding rules, runbooks, and Architecture Decision Records (ADRs).
  7. 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: Calls get_project_overview() followed by get_component("AuthService").

2. Planning Refactors & Blast Radius

User Prompt: "I want to modify the UserRepository interface. What other components will be impacted?"
Agent Action: Calls get_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: Calls update_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: Calls update_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)

Source distribution for code-compass-knowledge 0.1.0
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)

Table of built distributions (wheels) for code-compass-knowledge 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page