CodeCompress 0.15.0

Persistent code index for AI agents. Ask for exactly what you need.

---

What is CodeCompress?

CodeCompress is a code intelligence tool — available as both an MCP server and a standalone CLI — that gives AI coding agents instant memory of your codebase. Use whichever interface fits your workflow: the MCP server integrates directly with AI tools like Claude Code, while the CLI works anywhere you have a terminal.

Instead of scanning every file at the start of each conversation, agents query a persistent SQLite index to get exactly the symbols, types, and dependencies they need — in a fraction of the tokens.

Without CodeCompress	With CodeCompress
Agent reads 50+ files to understand your project	Agent calls project_outline — gets the full API surface in ~3–8k tokens
30–150k+ tokens wasted per session on context	80–90% reduction in context-loading tokens
Sub-agents each scan the same files independently	All agents share one persistent index
Bigger codebase = longer wait, every time	Index time is constant after first run (incremental)

Quick Start

Prerequisites

• .NET 10 SDK or later

Option A: MCP Server (recommended for AI tools)

Pick your tool and add the MCP server — that's it.

<details> <summary><strong>Claude Code</strong></summary>

claude mcp add --transport stdio codecompress -- dnx CodeCompress.Server --yes

</details>

<details> <summary><strong>VS Code / GitHub Copilot</strong></summary>

Create .vscode/mcp.json in your project:

{
  "servers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codecompress": {
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

</details>

<details> <summary><strong>Windsurf</strong></summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codecompress": {
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

</details>

<details> <summary><strong>Other MCP clients</strong></summary>

CodeCompress uses stdio transport. Point your client at:

dnx CodeCompress.Server --yes

</details>

<details> <summary><strong>Share with your team (.mcp.json)</strong></summary>

Commit this file at the root of your repo. Claude Code and VS Code pick it up automatically — every team member gets CodeCompress with zero setup:

{
  "mcpServers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

</details>

Option B: CLI (for terminals, scripts, and agents without MCP)

Install globally as a .NET tool:

dotnet tool install -g CodeCompress

Then use it from any terminal:

codecompress index --path /path/to/project
codecompress outline --path /path/to/project
codecompress search --path /path/to/project --query "MyClass"

The CLI and MCP server share the same index database — you can use both interchangeably. Run codecompress --help for all commands, or codecompress agent-instructions to generate a ready-to-paste instruction block for AI agents.

To update: dotnet tool update -g CodeCompress

2. Index your project

Your AI agent will call index_project automatically when it needs codebase context. You can also trigger it explicitly:

index_project(path: "/path/to/your/project")

First run does a full index — parses every source file and stores symbols in SQLite. Subsequent runs are incremental — only files whose SHA-256 hash changed get re-parsed.

3. Start coding

That's it. Your agent now has instant access to your codebase structure. It will automatically use tools like project_outline, get_symbol, and search_symbols instead of reading raw files.

How It Works

AI Agent  <── MCP (stdio) ──>  CodeCompress Server ──┐
                                                      │
Developer <── Terminal ────>   CodeCompress CLI ──────┤
                                                      │
                                                 Index Engine
                                                   /      \
                                          Language       SQLite Store
                                          Parsers      ~/.code-compress/
                                    (C#, Java, Go, TS,  index.db
                                    Rust, Python, Ruby, …)

Both the MCP server and CLI share the same index database — you can index with one and query with the other.

1. Index — CodeCompress walks your source files, hashes each one (SHA-256), and extracts symbols (functions, classes, types, constants) and dependencies (imports/requires) using language-specific parsers.

2. Store — Everything goes into a local SQLite database at .code-compress/index.db in the project directory. The database uses FTS5 virtual tables for fast full-text search.

3. Query — Agents call MCP tools to get compressed outlines, look up specific symbols by name, search across the codebase, or check what changed since a snapshot.

4. Stay current — Re-indexing is incremental. Only files whose content hash changed are re-parsed. Call index_project at the start of any session, or after making changes, and it completes in seconds.

Keeping the Index Up to Date

CodeCompress is designed to stay current with minimal effort:

Scenario	What to do
Starting a new agent session	Call index_project — takes seconds if nothing changed
After editing files	Call index_project again — only changed files are re-parsed
Tracking changes across sessions	Use snapshot_create before work, then changes_since to see what's different
Force a clean re-index	Call invalidate_cache then index_project

Tip for CLAUDE.md / system prompts: Add an instruction like "At the start of each session, call index_project to refresh the codebase index, then use project_outline to understand the project structure." This ensures your agent always has a fresh index.

Available MCP Tools

Indexing

Tool	What it does
index_project	Index a project directory (incremental by default)
snapshot_create	Create a named snapshot for tracking changes over time
invalidate_cache	Force a full re-index on next index_project call
list_repos	List all projects indexed in the global database

Context Assembly

Tool	What it does
assemble_context	One-shot context builder — searches symbols, retrieves source code, and builds a structured overview within a token budget. Replaces 5-10 manual tool calls with 1. Provide a query + optional active file, get back Markdown with file tree, source code blocks, and token usage stats. Large symbols auto-summarize.

When to use assemble_context: At the start of a task when you need broad context. For surgical retrieval of a specific symbol, use get_symbol or expand_symbol directly.

Querying

Tool	What it does
project_outline	Compressed API surface of the entire project — types, functions, signatures
get_symbol	Retrieve the full source code of a single symbol by name (supports Parent:Child qualified names)
get_symbols	Batch retrieve multiple symbols in one call (up to 50)
get_module_api	Complete public API of a single file/module
expand_symbol	Extract a single method from a large class (~60% fewer tokens than get_symbol)
get_hot_path	Return only the lines within a symbol that contain specific identifiers plus surrounding context (10–40x fewer tokens than the full body)
search_symbols	Full-text search across symbol names, signatures, parent types, and docs. Auto-retries with contains-match when exact FTS5 returns zero results.
search_text	Raw text search across file contents (with glob filtering)
topic_outline	Topic-based search with results grouped in outline format
find_references	Find all references to a symbol across the codebase

Change Tracking & Navigation

Tool	What it does
changes_since	Delta report — what files/symbols changed since a snapshot
file_tree	Annotated project file tree
dependency_graph	Import/require dependency graph for a file
project_dependencies	Inter-project dependency graph (.NET solutions)

Dependency Analysis

Tool	What it does
blast_radius	Reverse BFS — find all files affected if a given file or symbol changes
find_unused_symbols	Best-effort dead code detection — public symbols with no incoming references

Server Management

Tool	What it does
stop_server	Gracefully shut down the server to release resources and DLL locks

Note: MCP clients like Claude Code automatically restart the server on the next tool call, so stopping it is always safe.

MCP Prompts

CodeCompress ships 4 pre-built workflow prompts. In Claude Code and other MCP clients that support prompts, you can invoke them by name to load step-by-step workflow guidance directly into your context.

Prompt	Workflow
explore_codebase	index_project → project_outline → search_symbols → get_symbol
find_impact	index_project → blast_radius → find_references → dependency_graph
review_changes	snapshot_create → [make changes] → index_project → changes_since
debug_symbol	search_symbols → get_hot_path → get_symbol → find_references

Each prompt returns a ChatRole.User message with the full workflow, token estimates per tool, and guidance on when to prefer one tool over another.

CLI: Run codecompress prompts to list all prompts, or codecompress prompts --name explore_codebase to print the full text of a specific prompt.

Supported Languages

Language	Extensions	Status	Parser
Luau (Roblox)	.luau, .lua	Available	Regex/pattern-based
C# / .NET	.cs	Available	Tree-sitter AST
Blazor / Razor	.razor	Available	Directive extraction + C# delegation
Terraform / HCL	.tf, .tfvars	Available	Regex/pattern-based
Java	.java	Available	Tree-sitter AST
Go	.go	Available	Tree-sitter AST
TypeScript / JavaScript	.ts, .tsx, .js, .jsx, .mjs, .cjs	Available	Tree-sitter AST
Rust	.rs	Available	Tree-sitter AST
Python	.py, .pyi	Available	Tree-sitter AST
Ruby	.rb	Available	Tree-sitter AST
.NET Project Files	.csproj, .fsproj, .props	Available	XML-based
JSON Config	.json	Available	Tree-sitter AST
YAML Config	.yaml, .yml	Available	Structure-based

Adding a new language requires implementing a single ILanguageParser interface — no changes to storage, indexing, or MCP tools.

Where is my data stored?

All index data is stored in a single global database in your home directory:

~/.code-compress/index.db

• One SQLite database shared across all indexed projects
• Contains: file metadata, parsed symbols, dependencies, FTS5 search indexes, snapshots for every indexed project
• No data leaves your machine — no network calls, no telemetry
• Nothing is stored in your project directories — no .gitignore entries needed
• Access is confined to the server's launch directory and its descendants — see Access boundary

To clear the index for a specific project, call invalidate_cache (MCP) or codecompress invalidate-cache --path <root> (CLI). To list all indexed projects, use list_repos (MCP) or codecompress list (CLI).

Security

• Read-only — never modifies your source files
• Access boundary — the server is clamped to the directory it was launched from (and its descendants); it cannot index, query, or enumerate repositories outside that boundary (see below)
• Path traversal prevention — all file paths canonicalized and validated against the project root
• SQL injection prevention — all queries use parameterized statements
• Prompt injection safeguards — tool outputs are structured data; raw input is never echoed into freeform text
• Local only — no network calls, no telemetry, your code stays on your machine

Access boundary

To prevent one project's agent from reaching another repository's code or metadata, the server confines all tools to a boundary root resolved once at startup:

• Default: the server's launch working directory (where the MCP host started it). Any path at or below this directory is in-bounds — this includes sibling repositories when several repos live under one workspace folder.
• Override: set CODECOMPRESS_ROOT to pin the boundary explicitly (useful when the host launches the server from an unexpected directory).
• Allowlist: set CODECOMPRESS_ALLOWED_ROOTS (delimited by the OS path separator — ; on Windows, : elsewhere) to grant additional trusted roots for multi-repo workflows. Filesystem-root entries (/, C:\) are rejected as too broad.

Requests for paths outside the boundary are rejected with a uniform INVALID_PATH error (no information about the out-of-bounds path is leaked), and list_repos returns only repositories within the boundary.

Variable	Purpose	Default
CODECOMPRESS_ROOT	Boundary root the server may operate at or below	Launch working directory
CODECOMPRESS_ALLOWED_ROOTS	Extra trusted roots, OS-path-separator delimited	(none)

Agent Configuration

Paste the following into your CLAUDE.md, .cursorrules, system prompt, or agent configuration file to teach AI agents how to use CodeCompress:

Tip: You can also generate this block by running codecompress agent-instructions if you have the CLI installed.

# CodeCompress — Agent Instructions

CodeCompress is a code intelligence tool that provides compressed, symbol-level access
to the indexed codebase. Use it as your PRIMARY tool for code discovery instead of reading
raw files — it saves 80-90% tokens.

## Access Boundary

All paths are scoped to the server's launch directory (or `CODECOMPRESS_ROOT`). Out-of-bounds
paths are rejected with `INVALID_PATH`. Use `CODECOMPRESS_ALLOWED_ROOTS` for multi-repo workflows.

## Workflow

1. **Index first** — `index_project` (MCP) or `codecompress index --path <root>` (CLI).
   Builds/updates the symbol database. Incremental — only changed files are re-parsed.
2. **Assemble context** — `assemble_context` / `codecompress assemble` for one-shot task context.
   Combines search + source retrieval + overview in a single call — replaces 5-10 round-trips.
3. **Get an overview** — `project_outline` / `codecompress outline` for the full codebase structure.
   `topic_outline` / `codecompress topic-outline` to scope the overview to a specific topic.
4. **Search** — `search_symbols` / `codecompress search` for FTS5 full-text symbol search.
   `search_text` / `codecompress search-text` for raw file content (literals, comments, config).
5. **Read symbols** — `get_symbol` / `codecompress get-symbol` to retrieve exact source code.
   `expand_symbol` / `codecompress expand-symbol` for a single method (~60% fewer tokens).
   `get_hot_path` / `codecompress get-hot-path` for lines matching specific identifiers (10-40x savings).
   `get_symbols` / `codecompress get-symbols` to batch-retrieve up to 50 symbols at once.
   `get_module_api` / `codecompress get-module-api` for the public API surface of a file.
6. **Find references** — `find_references` / `codecompress find-references` to trace usage.
7. **Dependencies** — `dependency_graph` / `codecompress deps` for file import relationships.
   `blast_radius` / `codecompress blast-radius` for reverse impact analysis.
   `project_dependencies` / `codecompress project-deps` for inter-project (.NET solution) deps.
8. **Change tracking** — `snapshot_create` / `codecompress snapshot` to baseline the index.
   `changes_since` / `codecompress changes` for a symbol-level diff since the snapshot.
9. **Registry** — `list_repos` / `codecompress list` to see all indexed projects and their status.

## Tips

- Add `--json` to any CLI command for machine-readable output (snake_case keys).
- The index persists at `~/.code-compress/index.db` (global) — shared between MCP server and CLI.
- PREFER these tools over raw file reading. They are faster, more precise, and dramatically
  reduce token consumption.

Building from Source

git clone https://github.com/MCrank/code-compress.git
cd code-compress
dotnet build CodeCompress.slnx
dotnet test --solution CodeCompress.slnx

To run the MCP server locally:

dotnet run --project src/CodeCompress.Server

To configure a client to use your local build:

claude mcp add --transport stdio codecompress -- dotnet run --project /absolute/path/to/src/CodeCompress.Server

CLI Tool

The CLI provides the same capabilities as the MCP server — use whichever fits your workflow. Both share the same ~/.code-compress/index.db global database.

Installation

dotnet tool install -g CodeCompress

To update to the latest version:

dotnet tool update -g CodeCompress

Usage

# Index a project (must be run first)
codecompress index --path /path/to/project

# Assemble task-relevant context in one call (new!)
codecompress assemble --path /path/to/project --query "authentication" --budget 30000

# Get a compressed codebase overview
codecompress outline --path /path/to/project

# Search for symbols (auto-retries with contains-match on zero results)
codecompress search --path /path/to/project --query "Authentication*"

# Retrieve a specific symbol's source code
codecompress get-symbol --path /path/to/project --name MyClass:MyMethod

# Search raw file contents
codecompress search-text --path /path/to/project --query "TODO"

# Retrieve a nested method without loading the whole class (~60% token savings)
codecompress expand-symbol --path /path/to/project --name MyClass:MyMethod

# Return only lines matching specific identifiers within a symbol (~10-40x fewer tokens)
codecompress get-hot-path --path /path/to/project --name MyClass:MyMethod --identifiers "userId,status"

# Batch retrieve multiple symbols at once
codecompress get-symbols --path /path/to/project --names "Foo,Bar,Baz"

# Get the public API surface of a single file
codecompress get-module-api --path /path/to/project --module src/Core/Foo.cs

# Search by topic — returns results in outline format
codecompress topic-outline --path /path/to/project --topic authentication

# Find all references to a symbol across the codebase
codecompress find-references --path /path/to/project --name ISymbolStore

# View directory structure (no index required)
codecompress file-tree --path /path/to/project

# Show file-level dependency graph
codecompress deps --path /path/to/project

# Show inter-project dependencies (.NET solutions)
codecompress project-deps --path /path/to/project

# Snapshot + change tracking
codecompress snapshot --path /path/to/project --label before-refactor
codecompress changes --path /path/to/project --label before-refactor

# Delete index to force full re-index
codecompress invalidate-cache --path /path/to/project

JSON Output

Add --json to any command for machine-readable JSON output (snake_case keys matching MCP server output):

codecompress search --path /path/to/project --query "Parser" --json

Agent Instructions

Generate a ready-to-paste instruction block for AI agents:

codecompress agent-instructions

This outputs a markdown block you can paste into CLAUDE.md, system prompts, or agent configuration files to teach AI agents how to use the CLI for code discovery.

CLI-to-MCP Equivalence

CLI Command	MCP Tool	Description
index	index_project	Build/update the symbol database
assemble	assemble_context	One-shot context assembly within token budget
outline	project_outline	Compressed codebase overview
get-symbol	get_symbol	Retrieve symbol source code
expand-symbol	expand_symbol	Extract nested symbol (~60% fewer tokens)
get-hot-path	get_hot_path	Return only lines matching identifiers within a symbol
get-symbols	get_symbols	Batch retrieve multiple symbols
get-module-api	get_module_api	Public API surface of a file
search	search_symbols	FTS5 symbol search (auto contains-match fallback)
search-text	search_text	FTS5 raw content search
topic-outline	topic_outline	Topic-based search in outline format
find-references	find_references	Find all symbol references
changes	changes_since	Delta since snapshot
snapshot	snapshot_create	Create index snapshot
file-tree	file_tree	Directory tree
deps	dependency_graph	File-level dependency graph
project-deps	project_dependencies	Inter-project dependencies (.NET)
invalidate-cache	invalidate_cache	Force full re-index

License

MIT