CodeCompress 0.1.0-preview

<div align="center">

{ CodeCompress }

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

</div>

What is CodeCompress?

CodeCompress is an MCP server that gives AI coding agents instant memory of your codebase.

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

1. Add to your AI coding tool

Pick your tool and run one command — that's it.

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

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

Windows (not WSL)? Use cmd /c wrapper:

claude mcp add --transport stdio codecompress -- cmd /c 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"]
    }
  }
}

Windows (not WSL)? Change "command" to "cmd" and "args" to ["/c", "dnx", "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 / Windsurf / any MCP client</strong></summary>

CodeCompress uses stdio transport. Point your client at:

dnx CodeCompress.Server --yes

Or if you prefer a persistent global install:

dotnet tool install -g CodeCompress.Server
codecompress-server

</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>

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
                                      |
                                 Index Engine
                                   /      \
                          Language       SQLite Store
                          Parsers        ~/.codecompress/
                        (Luau, C#)      {project-hash}.db

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 ~/.codecompress/. Each project gets its own .db file, keyed by a hash of the project path. 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

Querying

Change Tracking & Navigation

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 locally at:

~/.codecompress/{project-hash}.db

• One SQLite database per project
• The project hash is derived from the canonical project path
• Contains: file metadata, parsed symbols, dependencies, FTS5 search indexes, snapshots
• No data leaves your machine — no network calls, no telemetry

To clear the index for a project, delete the corresponding .db file. To clear everything, delete the ~/.codecompress/ directory.

Security

• Read-only — never modifies your source files
• 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

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 (Optional)

A standalone CLI is available for testing and debugging outside of MCP:

dotnet tool install -g CodeCompress
codecompress index /path/to/project
codecompress outline /path/to/project

License

MIT