Codeix

🚀 codeix

Fast semantic code search for AI agents — find symbols, references, and callers across any codebase.

🚀 快速開始

以下是一些基本命令示例：

codeix                 # 啟動MCP服務器，監聽更改
codeix build           # 解析源文件，寫入.codeindex
codeix -r ~/project build  # 從特定目錄構建

✨ 主要特性

為何選擇codeix

AI編碼代理在處理代碼之前，大部分的令牌預算都花在了查找代碼上。它們會使用grep命令、讀取文件、再次使用grep命令、回溯等操作。在大型代碼庫中，代理可能會消耗數千個令牌來定位正確的函數，甚至可能完全錯過併產生錯誤結果。

Codeix為代理提供了一個預先構建的代碼庫地圖。一次結構化查詢就能返回符號名稱、文件、行範圍、簽名和父級信息，無需掃描和猜測。

現有工具的問題

codeix的不同之處

• 提交到git — 索引是一個.codeindex目錄，你可以將其與代碼一起提交。克隆倉庫時，索引已經存在，無需重新索引。
• 可共享 — 庫作者可以在他們的npm/PyPI/crates.io包中提供.codeindex。使用者可以立即導航依賴項。
• 可組合 — MCP服務器會自動發現依賴項索引並掛載它們。可以在一個地方查詢你的代碼和依賴項。
• 為大語言模型結構化 — 符號具有類型、簽名、父級關係和行範圍。代理在一次工具調用中就能獲得所需的信息，而無需從原始文本中拼湊。
• 文本搜索 — search --scope text專門針對註釋、文檔字符串和字符串字面量進行搜索。可以找到TODO、用戶報告的錯誤消息、函數文檔字符串的內容，而不會受到代碼的干擾。
• 快速 — 構建只需幾秒鐘，查詢只需幾毫秒。底層使用Rust + tree-sitter + 內存中的SQLite FTS5。

📦 安裝指南

# npm / npx — 無需安裝即可運行
npx codeix

# pip / uvx — 無需安裝即可運行
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# 或者從源代碼構建
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

所有渠道都安裝相同的單個二進制文件，無需運行時依賴。

💻 使用示例

基礎用法

# 為當前項目構建索引
codeix build

# 從特定目錄構建（發現所有下方的git倉庫）
codeix -r ~/projects build

# 啟動MCP服務器（默認命令，監聽更改）
codeix

# 或者顯式指定
codeix serve
codeix serve --no-watch

# 從特定目錄提供服務
codeix -r ~/projects serve

MCP客戶端配置

添加到你的MCP客戶端配置（例如Claude Desktop、Cursor）：

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

📚 詳細文檔

.codeindex 格式

一種用於結構化代碼索引的開放、可移植格式。它是普通的JSONL文件，可以與代碼一起提交，具有git友好的差異，使用grep和jq可以進行人類可讀的查看，沒有二進制文件。

.codeindex/
  index.json        # 清單：版本、名稱、語言
  files.jsonl       # 每個源文件一行（路徑、語言、哈希、行數）
  symbols.jsonl     # 每個符號一行（函數、類、導入，帶有簽名）
  texts.jsonl       # 每個註釋、文檔字符串、字符串字面量一行

任何可以解析JSON的工具都可以使用.codeindex。Codeix使用tree-sitter構建它，AI代理通過MCP（模型上下文協議）查詢它。

示例 — symbols.jsonl：

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

隨包發佈索引

在你的包中包含.codeindex，每個依賴於你的開發人員都可以立即導航你的API，無需設置，無需重新索引。適用於Git倉庫、npm、PyPI和crates.io。

MCP工具

有七個工具，無需設置。代理可以立即進行查詢，無需初始化、配置或刷新。

項目發現

從任何目錄啟動codeix。它會向下遍歷，並將每個包含.git/的目錄視為一個單獨的項目，每個項目都有自己的.codeindex。適用於單倉庫、單體倉庫、兄弟倉庫和git子模塊，無需配置。

支持的語言

Tree-sitter語法，在編譯時進行功能門控：

Markdown支持

Markdown文件會解析標題（ATX #和Setext下劃線樣式），這些標題會被索引為具有層次父子關係的section符號，從而支持提取目錄和導航文檔結構。 圍欄代碼塊會被提取為code文本條目，其父級為包含它們的部分。

嵌入式腳本

HTML、Vue、Svelte和Astro文件會進行預處理，以提取嵌入式<script>塊，然後使用JavaScript或TypeScript語法進行解析：

🔧 技術細節

設計原則

• 僅本地使用 — 無需網絡，無需API密鑰，可離線和隔離使用。
• 確定性 — 相同的源始終產生相同的索引（乾淨的差異）。
• 可組合 — 依賴項索引在查詢時會自動發現和掛載。
• 最小表面 — 7個查詢工具，無需管理管道。

架構

請參閱以獲取完整的架構決策記錄。

📄 許可證

MIT OR Apache-2.0