CodeCompress.linux-arm64 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.

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:

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

Context Assembly

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

Change Tracking & Navigation

Dependency Analysis

Server Management

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.

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

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.

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

License

MIT