Code Compress

AI代理的持久代码索引。确切地问你需要什么。

______________________________________________________________________

什么是CodeCompress？

CodeCompress是一个 代码智能工具 --可用作两者 MCP服务器 和一个 独立CLI --这赋予了AI编码代理 代码库的即时记忆.使用适合您工作流程的任何界面：MCP服务器直接与Claude Code等AI工具集成，而CLI在任何有终端的地方都可以工作。

代理不会在每次对话开始时扫描每个文件，而是查询一个持久的SQLite索引，以获取他们所需的符号、类型和依赖关系——只需一小部分令牌。

快速开始

先决条件

• .NET 10 SDK 或更高版本

选项A:MCP服务器（推荐用于AI工具）

选择你的工具并添加MCP服务器——就是这样。

Claude Code

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

VS Code / GitHub Copilot

创建 .vscode/mcp.json 在您的项目中：

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

Claude Desktop

增添 claude_desktop_config.json:

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

Cursor

创建 .cursor/mcp.json 在您的项目中：

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

Windsurf

增添 ~/.codeium/windsurf/mcp_config.json:

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

Other MCP clients

CodeCompress使用stdio传输。为您的客户指出：

dnx CodeCompress.Server --yes

Share with your team (.mcp.json)

将此文件提交到仓库的根目录。Claude Code和VS Code会自动获取它——每个团队成员都可以在零设置的情况下获得CodeCompress：

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

选项B:CLI（用于没有MCP的终端、脚本和代理）

作为全局安装。NET工具：

dotnet tool install -g CodeCompress

然后从任何终端使用它：

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

CLI和MCP服务器共享同一个索引数据库，可以互换使用。跑 codecompress --help 对于所有命令，或 codecompress agent-instructions 为AI代理生成即贴指令块。

选项C：Web仪表板（本地UI）

启动暗模式的ExpressRoute仪表板，从浏览器浏览索引存储库、搜索符号并触发重新索引：

codecompress web

打开时间 http://localhost:7070 默认情况下。选项：

codecompress web --port 8080        # custom port
codecompress web --open             # open browser automatically
codecompress web --bind 0.0.0.0    # bind to all interfaces (LAN access)

仪表板显示相同的全局 ~/.code-compress/index.db 作为MCP服务器和CLI，无需单独设置。

要更新，请执行以下操作： dotnet tool update -g CodeCompress

2.为你的项目建立索引

你的AI代理会打电话给你 index_project 当它需要代码库上下文时自动执行。您还可以显式触发它：

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

第一次运行做了一个 全文索引 --解析每个源文件并将符号存储在SQLite中。后续运行是 渐进的 --只有SHA-256哈希值更改的文件才会被重新解析。

3.开始编码

就是这样。你的代理现在可以即时访问你的代码库结构。它将自动使用以下工具 project_outline, get_symbol，以及 search_symbols 而不是读取原始文件。

运作原理

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

MCP服务器和CLI共享同一个索引数据库——您可以使用其中一个进行索引，使用另一个进行查询。

1. 索引 --CodeCompress遍历您的源文件，对每个文件进行哈希（SHA-256），并使用特定语言的解析器提取符号（函数、类、类型、常量）和依赖关系（导入/要求）。

1. 商店 --所有内容都会进入本地SQLite数据库 .code-compress/index.db 在项目目录中。该数据库使用FTS5虚拟表进行快速全文搜索。

1. 查询 --代理调用MCP工具以获取压缩轮廓，按名称查找特定符号，在代码库中搜索，或检查自快照以来发生了什么变化。

1. 与时俱进 --重新索引是增量的。只有内容哈希值更改的文件才会被重新解析。呼叫 index_project 在任何会话开始时，或在进行更改后，它都会在几秒钟内完成。

保持索引最新

CodeCompress旨在以最小的努力保持最新状态：

CLAUDE.md/系统提示提示： 添加如下指令 *“每次会话开始时，请致电 index_project 要刷新代码库索引，请使用 project_outline 了解项目结构。"* 这可以确保您的代理始终有一个新的索引。

可用的MCP工具

索引

上下文组装

何时使用 assemble_context: 在任务开始时，当你需要广泛的背景时。对于特定符号的外科检索，请使用 get_symbol 或 expand_symbol 直接。

查询

更改跟踪和导航

相关性分析

服务器管理

注： 像Claude Code这样的MCP客户端会在下一次工具调用时自动重启服务器，因此停止它总是安全的。

MCP提示

CodeCompress提供4个预构建的工作流提示。在Claude Code和其他支持提示的MCP客户端中，您可以按名称调用它们，将分步工作流指南直接加载到您的上下文中。

每个提示符返回一个 ChatRole.User 该消息包含完整的工作流程、每个工具的令牌估计以及何时选择一种工具而非另一种工具的指导。

CLI： 跑 codecompress prompts 列出所有提示，或 codecompress prompts --name explore_codebase 打印特定提示的全文。

支持的语言

添加新语言需要实现一个 ILanguageParser 接口——存储、索引或MCP工具没有变化。

我的数据存储在哪里？

所有索引数据都存储在 单一全局数据库 在您的主目录中：

~/.code-compress/index.db

• 一个SQLite数据库在所有索引项目中共享
• 包含：文件元数据、解析符号、依赖关系、FTS5搜索索引、每个索引项目的快照
• 没有数据离开您的机器 --无网络呼叫，无遥测
• 项目目录中没有存储任何内容——没有 .gitignore 所需条目

要清除特定项目的索引，请调用 invalidate_cache （MCP）或 codecompress invalidate-cache --path （CLI）。要列出所有索引项目，请使用 list_repos （MCP）或 codecompress list （CLI）。

安全

• 只读 --永远不要修改源文件
• 路径遍历预防 --根据项目根进行规范化和验证的所有文件路径
• SQL注入预防 --所有查询都使用参数化语句
• 快速注射防护措施 --工具输出是结构化数据；原始输入永远不会回显为自由文本
• 仅限本地 --没有网络调用，没有遥测，你的代码留在你的机器上

代理配置

将以下内容粘贴到您的 CLAUDE.md, .cursorrules、系统提示或代理配置文件，以教导AI代理如何使用CodeCompress：

提示： 您还可以通过运行以下命令来生成此块 codecompress agent-instructions 如果您安装了CLI。

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

## Workflow

1. **Index first** — `index_project` (MCP) or `codecompress index --path ` (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 + file overview within a token budget.
3. **Get an overview** — `project_outline` / `codecompress outline` for the full codebase structure.
4. **Search** — `search_symbols` / `codecompress search` for FTS5 full-text symbol search.
   `search_text` / `codecompress search-text` for raw file content search.
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).
6. **Find references** — `find_references` / `codecompress find-references` to trace usage.
7. **Dependencies** — `dependency_graph` / `codecompress deps` for import relationships.

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

从源头构建

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

要在本地运行MCP服务器：

dotnet run --project src/CodeCompress.Server

要配置客户端以使用本地版本，请执行以下操作：

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

CLI工具

CLI提供与MCP服务器相同的功能——使用适合您工作流程的功能。两者共享相同 ~/.code-compress/index.db 全球数据库。

安装

dotnet tool install -g CodeCompress

要更新到最新版本：

dotnet tool update -g CodeCompress

用法

# 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

# Launch the web dashboard
codecompress web [--port 7070] [--bind localhost] [--open]

JSON输出

添加 --json 对于机器可读JSON输出的任何命令（匹配MCP服务器输出的snake_case密钥）：

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

代理说明

为AI代理生成可粘贴指令块：

codecompress agent-instructions

这将输出一个可以粘贴到其中的markdown块 CLAUDE.md、系统提示或代理配置文件，以教导AI代理如何使用CLI进行代码发现。

CLI到MCP的等效性

许可证

麻省理工学院