██████╗ ██████╗ ██████╗ ███████╗███╗   ███╗██╗   ██╗███╗   ██╗ ██████╗██╗  ██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝████╗ ████║██║   ██║████╗  ██║██╔════╝██║  ██║
██║     ██║   ██║██║  ██║█████╗  ██╔████╔██║██║   ██║██╔██╗ ██║██║     ███████║
██║     ██║   ██║██║  ██║██╔══╝  ██║╚██╔╝██║██║   ██║██║╚██╗██║██║     ██╔══██║
╚██████╗╚██████╔╝██████╔╝███████╗██║ ╚═╝ ██║╚██████╔╝██║ ╚████║╚██████╗██║  ██║
╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝

Claude code的零配置、令牌高效代码探索——无MCP服务器、无Python、无数据库

问题

当Claude Code探索代码库时，最简单的方法是读取整个文件。一个800行的文件大约需要8000个令牌。阅读十个文件来找到一个函数，在编写一行代码之前，你已经消耗了80000个令牌。

其他解决方案添加了MCP服务器、Python运行时或数据库，所有这些都会消耗自己的资源并增加复杂性。codemunch采取了不同的方法： 一个运行时没有基础设施开销的纯Claude Code插件。

codemunch解决了这个问题。 它会自动将您的代码库索引到一个平面JSON文件中，并让Claude获取所需的确切20行，而不是800行文件。没有服务器进程，没有数据库守护进程，没有Python依赖性——只需安装并开始使用它。```
Without codemunch: read auth.ts (800 lines) → ~8,000 tokens
With codemunch: fetch validateToken() → ~35 tokens

Savings: 99.6%

______________________________________________________________________

## 为什么要使用codemunch？

Claude Code代币账单。每次文件读取都会消耗令牌，而这些令牌中的大多数都浪费在您不需要看到的代码上。

|场景|无代码审查|有代码审查|节省|
|---|---|---|---|
|查找函数|读取完整文件（约8000个标记）| `search` + `fetch` （约47个代币）| **99.4%** |
|跟踪符号的所有用法|读取14个文件（约112000个令牌）| `refs` （约45个代币）| **99.96%** |
|了解项目结构|读取10+个文件（约80000个令牌）| `explore` （约200个代币）| **99.75%** |
|典型调试会话（30次查找）|~240000个令牌|~1200个令牌| **99.5%** |

### 设定基准的上下文节省

我们将codemunch与三个真正的开源仓库进行了基准测试——在每个仓库上运行5个典型的探索任务，并在没有codemunch的情况下测量代币消费：

|回购|规模|传统|代码咀嚼|节省|
|---|---|---|---|---|
| expressjs/cors |6个文件，约8K个令牌|1810|1281个令牌| **93.2%** |
| 奶牛 |82个文件，约52K个令牌|24565个令牌|2316个令牌| **90.6%** |
| 快/快 |290个文件，约468K个令牌|103891个令牌|3174个令牌| **96.9%** |
| **组合（15个任务）** | **378张图片** | **147266个代币** | **6771个代币** | **95.4%** |

最佳情况： **节省99.0%** （查找所有参考文献 `.send()` 跨越139个测试文件-- `refs` 而不是grep+读取文件）。
最坏情况： **节省69.8%** （多获取相关函数——仍然比读取一个完整文件便宜）。

> 完整的基准方法和每项任务的细分： docs/benchmark-results.md

那是 **上下文使用量减少约22倍** 平均而言，这意味着：

- **长对话** --你在克劳德的上下文窗口内保持良好状态，而不是在任务中途达到极限
- **降低成本** -每项任务消耗的代币越少，您的API账单就越少
- **更快的响应** --克劳德需要处理的输入更少，意味着回复更快
- **更好的结果** --Claude只看到相关的代码，而不是数千行的噪音，从而得到更专注和准确的响应

______________________________________________________________________

## 运作原理

codemunch使用a **三层发动机** --它为每种语言选择最佳可用工具，并自动回退。无需配置。```
Tier 1 — LSP (Language Server)
Byte-exact symbol boundaries, type signatures, cross-file references.
Same engine powering "Go to Definition" in VS Code.
↓ not available?
Tier 2 — Universal ctags
40+ languages. Near-exact boundaries. Ships with most Unix systems.
↓ not available?
Tier 3 — ripgrep
Works on literally any language via regex patterns.
If rg is installed, codemunch works.

自动索引

你永远不需要手动索引。 代码自动读取：

• 先用：检测堆栈、配置引擎，并在运行任何命令时构建完整索引
• 后续用途：检查自上次索引以来文件是否已更改，并仅对不同的部分进行增量重新索引
• 增量更新：跟踪每个文件的git blob哈希值——仅重新处理实际更改的文件```
  First /codemunch:search → auto-detects stack → builds full index → runs your search
  Next /codemunch:fetch → checks git diff → 2 files changed → re-indexes those 2 → fetches symbol
  Later /codemunch:refs → checks git diff → no changes → runs immediately

______________________________________________________________________

## 快速启动```bash
# 1. Add the marketplace and install the plugin
/plugin marketplace add benmarte/codemunch
/plugin install codemunch@codemunch

# 2. Start using it — indexing happens automatically
/codemunch:explore

# 3. Search for symbols
/codemunch:search validateToken

# 4. Read just that function — not the whole file
/codemunch:fetch validateToken

# 5. Find every place it's called
/codemunch:refs validateToken

就是这样。不 /codemunch:index 需要。没有要创建的配置文件。只需安装和使用。

用户指南

探索新的代码库

当你第一次打开一个项目时，从 /codemunch:explore 了解情况：```bash

Get a bird's-eye view of the whole project

/codemunch:explore

Drill into a specific directory

/codemunch:explore src/api/

Outline a single file

/codemunch:explore src/api/invoices.ts

这向您显示了类层次结构、入口点和最大的符号——所有这些都不需要读取任何源文件。代币成本：低于200。

### 查找符号

使用 `/codemunch:search` 对于所有符号查找，它处理模糊名称匹配和结构化过滤器：```bash
# Fuzzy name search
/codemunch:search validate          # matches validateToken, validateEmail, etc.
/codemunch:search AuthService       # exact class name
/codemunch:search inv               # matches Invoice, invalidate, invoiceRouter

# Filter by kind
/codemunch:search kind:class        # all classes
/codemunch:search kind:interface    # all interfaces
/codemunch:search kind:method       # all methods

# Filter by file
/codemunch:search file:auth         # symbols in auth-related files

# Filter by container (class/module)
/codemunch:search in:AuthService    # methods on AuthService

# Filter by signature
/codemunch:search sig:Promise       # functions returning Promise

# Combine filters
/codemunch:search kind:method in:Invoice              # Invoice methods
/codemunch:search validate kind:function              # functions named "validate*"
/codemunch:search kind:interface file:api             # interfaces in api files

输出：```
Found 6 symbols matching "validate":

1. validateToken function src/auth/tokens.ts:142 AuthService
2. validateInvoice function src/lib/validation.ts:89 —
3. validateAmount function src/lib/validation.ts:112 —
4. validateEmail method src/models/user.ts:34 UserModel
5. validateExpense function convex/expenses.ts:67 —
6. validateDate function src/utils/dates.ts:23 —

Use /codemunch:fetch to read the source of any symbol.
Tokens used: 12

### 读取符号源

一旦你找到了你需要的东西，使用 `/codemunch:fetch` 阅读这个符号：```bash
/codemunch:fetch validateToken
/codemunch:fetch AuthService
/codemunch:fetch getUserById

输出：```
📍 validateToken [function] src/auth/tokens.ts:142–163
Signature: validateToken(token: string): Promise
Container: AuthService | References: 14
─────────────────────────────────────────
async function validateToken(token: string): Promise {
...20 lines of source...
}
─────────────────────────────────────────
Tokens: ~35 (saved ~8,400 vs reading full file)

如果多个文件中存在相同的名称，您将得到一个编号的消歧列表。

### 查找参考文献

使用 `/codemunch:refs` 为了找到每个地方，使用了一个符号：```bash
/codemunch:refs validateToken

输出：```
14 references to validateToken:

src/api/auth.ts:23 authRouter.post('/login', validateToken, ...)
src/api/invoices.ts:45 export const getInvoice = [validateToken, ...]
src/middleware/index.ts:12 app.use('/api', validateToken)
tests/auth.test.ts:34 await validateToken('expired-token')
...

Tokens: ~45 (saved ~42,000 vs reading 14 files)

使用LSP进行语义精确（注释或字符串中没有误报）；回到ripgrep。

### 检查状态

查看您的引擎配置、索引新鲜度和会话节省：```bash
/codemunch:status
``````
codemunch status

Engines:
TypeScript  → typescript-language-server (LSP) ✅
Python      → universal-ctags ✅
Bash        → ripgrep ✅

Index:
Built:      2026-03-11 02:14 (3 hours ago)
Symbols:    1,247 across 89 files
Status:     ✅ fresh (auto-updates on next query if stale)

Session stats:
Fetches:        23
Tokens used:    ~840
Tokens saved:   ~186,000
Savings:        99.5%

命令

支持的语言

第1层——通过LSP（字节精确+类型信息+跨文件引用）

语言 · 语言服务器 · 可用性
Types/JavaScript · typescript-language-server · 通常使用VS代码
python pylsp 或 pyright · 可能
去吧 · gopls · 使用Go工具链
生锈 · rust-analyzer · 生锈
C/C++ · clangd 或 ccls · 经常
CNET · omnisharp 或 csharp-ls · 与VS/骑手
Java jdtls · IntelliJ
Kotlin · kotlin-language-server · 也许吧
红宝石 · solargraph 或 ruby-lsp · 也许吧
PHP · phpactor 或 intelephense · 也许吧
Swift · sourcekit-lsp · macOS与Xcode
Lua · lua-language-server · 也许吧
齐格 · zls · 使用Zig工具链
灵丹妙药 · elixir-ls 或 lexical · 也许吧
哈斯克尔 · haskell-language-server · 也许吧
OCaml · ocamllsp · 也许吧
Bash · bash-language-server · 很少

codemunch会自动检测所有这些，无需配置。

第2层——通过通用ctags（40多种语言，无需服务器）

ActionScript、Ada、Ant、Awk、Bash、C、C++、C#、Clojure、CoffeeScript、D、Elixir、Erlang、Fortran、Go、Groovy、Haskell、HTML、Java、JavaScript、JSON、Julia、Kotlin、Lisp、Lua、Make、Matlab、Objective-C、OCaml、Pascal、Perl、PHP、PowerShell、Python、R、Ruby、Rust、Scala、Scheme、Shell、SQL、Swift、Tcl、TypeScript、Verilog、VHDL、Vim、YAML、Zig等。

如果没有，请安装ctags：```bash
brew install universal-ctags # macOS
apt install universal-ctags # Ubuntu/Debian
scoop install ctags # Windows

### 第3层——通过ripgrep（任何语言）

TypeScript、JavaScript、Python、Go、Rust、Ruby、Java、Kotlin、C、C++、PHP、Swift、Lua、Zig和Bash的内置模式。

对于任何其他语言，添加自定义模式 `.claude/codemunch/config.json`:```json
{
"custom_patterns": {
"solidity": {
"function": "^\\s*(function|modifier|event)\\s+(\\w+)",
"class":    "^(contract|library|interface)\\s+(\\w+)"
},
"hcl": {
"function": "^(resource|data|module|variable|output)\\s+\"(\\w+)\"\\s+\"(\\w+)\""
},
"prisma": {
"class": "^(model|enum)\\s+(\\w+)\\s+\\{"
}
}
}

需求

克劳德代码 --这是一个Claude Code插件，而不是MCP服务器。

为了获得最佳体验，请安装 全部 以下。codemunch将它们用作后备链（LSP→ 标签→ ripgrep），因此拥有这三个可以确保最大的精度和覆盖范围：```bash

macOS (Homebrew)

brew install universal-ctags ripgrep jq

Ubuntu / Debian

apt install universal-ctags ripgrep jq

Windows (Scoop)

scoop install ctags ripgrep jq

|工具|为什么|需要？ |
|---|---|---|
| **LSP服务器** |最精确的——精确的类型、签名、跨文件引用。如果您使用VS Code，通常已经安装。|推荐|
| **通用ctags** |40多种语言的快速符号提取。当LSP不适用于某一语言时使用。|推荐|
| **ripgrep** |最后手段模式匹配。也用于参考搜索回退。|推荐|
| **jq公司** |快速JSON索引查询。如果不可用，则返回Python。|可选|

codemunch仅适用于 **一** 虽然有上述三种方法，但拥有这三种方法会给你带来最好的结果——LSP用于精度，ctags用于广度，ripgrep作为安全网。

**没有MCP服务器。没有Python包。没有数据库。没有安装npm。无后台进程。没有汇编。**

______________________________________________________________________

## 安装```bash
# Add the marketplace and install
/plugin marketplace add benmarte/codemunch
/plugin install codemunch@codemunch

然后运行一次性init让Claude自动使用codemunch：```bash
/codemunch:init

这将为您的项目添加说明 `CLAUDE.md` 所以克劳德 **自动地** 使用codemunch进行所有代码探索——您永远不必键入 `/codemunch:search` 你自己。只要需要查找或读取代码，Claude就会这样做。

或者，手动将说明添加到项目的 `CLAUDE.md`:```markdown
## Code Exploration — MANDATORY (codemunch)

You MUST use codemunch for ALL code exploration. This is NON-NEGOTIABLE. Do NOT ignore this rule.
Reading full files when a codemunch command exists for the task is a violation of your instructions.

### Rules (enforced, no exceptions)

1. **NEVER read a full source file to understand what a function/class does.** Use `/codemunch:fetch ` instead. It reads ~35 tokens instead of ~8,000.
2. **NEVER use Grep or Glob to find functions, classes, or types.** Use `/codemunch:search ` instead. Supports filters: `kind:class`, `file:auth`, `in:ClassName`, `sig:ReturnType`.
3. **NEVER read multiple files to understand project structure.** Use `/codemunch:explore [path]` instead.
4. **NEVER use Grep to find symbol usages.** Use `/codemunch:refs ` instead.
5. **The ONLY exception**: Use Read when you need to Edit a file, since Edit requires file content in context.

### Decision tree

- Need to find a symbol? → `/codemunch:search`
- Need to read a symbol's code? → `/codemunch:fetch`
- Need to understand structure? → `/codemunch:explore`
- Need to find references? → `/codemunch:refs`
- Need to edit a file? → Read first, then Edit (this is the ONLY valid use of Read for source files)

The index auto-updates — no manual indexing needed.

执行钩（PreToolUse）

codemunch包括 PreTool使用挂钩 当Claude试图执行以下操作时，它会以编程方式将其推向codemunch命令 Read, Grep，或 Glob 源文件。钩子随插件自动安装，无需设置。

它是如何工作的：

钩子不会阻挡——它注入了引导，所以克劳德会自我纠正。结合 CLAUDE.md 说明（来自 /codemunch:init)，这实现了约98%的执行率，而仅使用指令的执行率约为60-80%。

禁用强制：

如果您更喜欢将codemunch作为选择加入而不是强制执行，请使用单个命令禁用它：```bash
/codemunch:disable

这将关闭PreToolUse挂钩 **和** 一步即可删除CLAUDE.md强制规则。codemunch命令仍然有效，只是不会被执行。

要重新启用：```bash
/codemunch:enable

升级

如果您已经拥有升级命令```bash

/codemunch:upgrade

#### 如果您没有升级命令（较旧的安装）

插件系统在本地缓存市场克隆。如果您的安装早于升级命令，则需要先更新市场克隆：```bash
# 1. Update the marketplace clone
cd ~/.claude/plugins/marketplaces/codemunch && git pull origin main

# 2. Reinstall the plugin
/plugin update codemunch@codemunch

如果 /plugin update 仍然显示“已为最新版本”，卸载并重新安装：```bash
/plugin uninstall codemunch@codemunch
/plugin install codemunch@codemunch

在此之后， `/codemunch:upgrade` 将可用于未来的所有更新。

### 自动更新检查

codemunch在会话开始时每天检查一次新版本。如果有可用的更新，您将看到一条通知：```
Update available: v1.1.0 → v1.2.0
Run /codemunch:upgrade to update.

该检查是轻量级的（单个GitHub API调用，3秒超时，缓存24小时），并且从不阻止启动。

初始化（或手动设置）后，只需正常与Claude交谈：```
"Fix the bug in the validateToken function"
→ Claude auto-uses /codemunch:search to find it, /codemunch:fetch to read it, then fixes it

"How does the auth flow work?"
→ Claude auto-uses /codemunch:explore and /codemunch:refs to trace the flow

______________________________________________________________________

## 索引文件

codemunch写道 `.claude/codemunch/index.json` 添加到您的项目中 `.claude/codemunch/` 到你的 `.gitignore` 自动。索引是一个扁平的JSON文件——没有数据库，没有守护进程，也没有后台进程。

每个符号条目：```json
{
"name": "validateToken",
"kind": "function",
"file": "src/auth/tokens.ts",
"start_line": 142,
"end_line": 163,
"signature": "validateToken(token: string): Promise",
"container": "AuthService",
"engine": "lsp"
}

该指数还跟踪 file_hashes --每个文件到其git blob哈希的映射。这为增量重新索引提供了动力：当您编辑3个文件时，只有这3个文件会被重新处理，而不是整个项目。

您永远不需要手动重新索引。当任何查询命令检测到过时文件时，索引会自动更新。如果你想彻底重建，请使用 /codemunch:index --force.

插件结构```

codemunch/
├── .claude-plugin/
│ ├── plugin.json # plugin manifest
│ └── hooks/
│ └── hooks.json # PreToolUse + SessionStart hook registration
├── hooks/
│ ├── pretooluse.sh # enforcement hook (disable via env or config)
│ └── sessionstart.sh # update check on startup (once per day)
├── skills/
│ ├── detect-lsp/ # detects installed language servers
│ ├── index/ # builds symbol index (LSP → ctags → rg)
│ ├── staleness-gate/ # auto-checks index freshness before queries
│ ├── fetch/ # reads exact symbol source from index
│ ├── search/ # queries index without reading files
│ ├── lsp/ # direct LSP ops: refs, hover, definition, rename
│ ├── ctags/ # ctags indexing and JSON parsing
│ └── rg-fallback/ # ripgrep pattern-based indexing + custom patterns
└── commands/
├── init.md # /codemunch:init (one-time CLAUDE.md setup)
├── search.md # /codemunch:search
├── fetch.md # /codemunch:fetch
├── refs.md # /codemunch:refs
├── explore.md # /codemunch:explore
├── status.md # /codemunch:status
├── index.md # /codemunch:index (manual, rarely needed)
├── disable.md # /codemunch:disable (turn off enforcement)
├── enable.md # /codemunch:enable (turn enforcement back on)
└── upgrade.md # /codemunch:upgrade (check for updates)
```

codemunch如何比较

codemunch与上下文模式

上下文模式 是一个MCP服务器，它将原始工具输出（bash、web获取、grep）沙盒化，以将其排除在上下文窗口之外。它解决了一个与codemunch不同的问题——以下是它们的比较：

| 许可证 ELv2（限制性）

关键见解： 它们是互补的，而不是竞争的。codemunch防止浪费代币 之前 它们发生了（通过只阅读你需要的符号）。上下文模式捕获浪费的令牌 之后 它们会发生（通过沙盒处理大型工具输出）。运行这两种模式的用户可以在代码探索（codemunch）和bash/web/grep输出（上下文模式）上进行保存。

资源开销

codemunch的设计目标是 零开销基础设施 --没有服务器，没有数据库，没有npm。如果你想以绝对最小的资源占用节省上下文，codemunch是一个更轻便的选择。如果你需要更广泛的覆盖范围（沙盒化所有工具输出、会话连续性），上下文模式会以牺牲更多基础设施为代价来增加覆盖范围。

常见问题解答

我必须打字吗 /codemunch:search 每一次？

不，快跑 /codemunch:init 每个项目一次——它为您的 CLAUDE.md 因此，每当需要探索代码时，Claude都会自动使用codemunch。你只需正常地与克劳德交谈，它就会在幕后使用codemunch。

我需要跑步吗 /codemunch:index 在使用其他命令之前？

否。该索引在首次使用时自动构建，并通过增量重新索引保持最新。你永远不需要考虑它。

自动索引是如何工作的？

每个查询命令（搜索、获取、引用、探索）都会首先运行一个轻量级的过时性检查。它将索引时间戳与 git diff 查找已更改的文件。如果文件发生更改，则只有这些文件会被重新索引。如果不存在索引，则构建完整索引。新索引的开销可以忽略不计（\<100ms）。

如果多个文件中存在相同的函数名怎么办？

fetch 显示一个编号的消歧列表，并询问您想要哪个。

这适用于monorepos吗？

对。从repo根目录运行任何命令。使用 file: 在搜索中筛选特定包的范围。

codemunch会把我的代码发送到任何地方吗？

不，一切都是本地的。该指数位于 .claude/codemunch/ 在你的项目中。没有网络呼叫。

为什么不直接使用LSP？

codemunch确实将LSP用于需要它的操作（引用、悬停、重命名）。索引层添加了快速的离线搜索，而无需为每次查找都启动语言服务器，还为没有LSP的语言添加了ctags/rg回退。

我可以强制重新索引吗？

对： /codemunch:index --force 从头开始重建。

灵感

概念上受到启发 格雷维尔/日本食品药品监督管理局 --Python MCP服务器，使用树形图进行基于符号的检索。这个插件是一个独立的重新实现，作为原生Claude Code插件：没有共享代码，没有MCP服务器，没有Python依赖关系，没有数据库——只有一个扁平的JSON索引和40多种语言，通过LSP/ctags/rg层系统。

许可证

麻省理工学院——见 许可证