codemunch (Benmarte)

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

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代币账单。每次文件读取都会消耗令牌，而这些令牌中的大多数都浪费在您不需要看到的代码上。

设定基准的上下文节省

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

最佳情况： 节省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

______________________________________________________________________

快速启动

# 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 了解情况：

# 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 对于所有符号查找，它处理模糊名称匹配和结构化过滤器：

# 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 阅读这个符号：

/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 为了找到每个地方，使用了一个符号：

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

检查状态

查看您的引擎配置、索引新鲜度和会话节省：

/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（字节精确+类型信息+跨文件引用）

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：

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:

{
  "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），因此拥有这三个可以确保最大的精度和覆盖范围：

# macOS (Homebrew)
brew install universal-ctags ripgrep jq

# Ubuntu / Debian
apt install universal-ctags ripgrep jq

# Windows (Scoop)
scoop install ctags ripgrep jq

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

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

______________________________________________________________________

安装

# Add the marketplace and install
/plugin marketplace add benmarte/codemunch
/plugin install codemunch@codemunch

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

/codemunch:init

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

或者，手动将说明添加到项目的 CLAUDE.md:

## 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作为选择加入而不是强制执行，请使用单个命令禁用它：

/codemunch:disable

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

要重新启用：

/codemunch:enable

升级

如果您已经拥有升级命令

/codemunch:upgrade

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

插件系统在本地缓存市场克隆。如果您的安装早于升级命令，则需要先更新市场克隆：

# 1. Update the marketplace clone
cd ~/.claude/plugins/marketplaces/codemunch && git pull origin main

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

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

/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文件——没有数据库，没有守护进程，也没有后台进程。

每个符号条目：

{
  "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不同的问题——以下是它们的比较：

关键见解： 它们是互补的，而不是竞争的。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层系统。

______________________________________________________________________

许可证

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