CICADA

CICADA

警告

⚠️ 免责声明 — 如今的 AI Agent 与本项目构思之初相比，运作方式已截然不同。在当前基准测试中，使用代码智能工具对前沿模型几乎没有任何帮助。CICADA 已停止维护，我不建议使用它或任何其他“代码智能”工具。

---

Code Intelligence：Contextual Analysis、Discovery 和 Attribution

面向 AI 代码助手的上下文压缩 – 为你的 AI 提供对 17+ 种语言的结构化、节省 token 的访问能力，包括 Elixir、Python、TypeScript、JavaScript、Rust 等。

减少最多 50% 的等待时间 · 减少最多 70% 的 token · 减少最多 99% 的解释工作 上下文越精简，质量越好

快速安装 · 安全性 · 开发者 · AI 助手 · 文档

为什么选择 CICADA？

核心问题： AI 代码助手在盲目搜索上浪费上下文。当你只需要一个函数签名时，Grep 却会倾倒整个文件，留给实际推理的空间就更少了。

上下文压缩方案

CICADA 不会倾倒原始文本，而是为你的 AI 提供结构化、预先索引的知识：

你将获得

• AST 级索引 – 模块/函数/类定义及其签名、规范和文档
• 支持 17+ 种语言 – Elixir、Python、TypeScript、JavaScript、Rust、Go、Java、Kotlin、Scala、C/C++、Ruby、C#、Visual Basic、Dart、PHP、Erlang（测试版）
• 完整的调用位置跟踪 – 跟踪所有支持语言中的别名、导入和动态引用
• 语义搜索 – 通过关键词提取或嵌入（集成 Ollama）按概念查找代码
• Git + PR 归因 – 呈现代码存在的原因，而不只是代码的内容
• 依赖分析 – 双向跟踪（哪些内容调用了它，以及它调用了哪些内容）
• 自动语言检测 – 在多语言代码库中无缝运行

安装

# 1. Install uv (if needed)
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# In your repo
cicada claude   # or: cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode, cicada zed

uvx cicada-mcp claude   # or cursor, vs

claude mcp add cicada uvx cicada-mcp

gemini mcp add cicada uvx cicada-mcp

codex mcp add cicada uvx cicada-mcp

kimi mcp add --transport stdio cicada -- cicada-mcp

安装后可用的命令：

• cicada [claude|cursor|vs|gemini|codex|opencode|zed] - 为每个项目提供一键交互式设置
• cicada-mcp - MCP 服务（由编辑器自动启动）
• cicada serve - 启动 REST API 服务，通过 HTTP 访问所有 MCP 工具
• cicada status - 显示索引状态、PR 索引、链接状态、Agent 文件和 MCP 配置
• cicada stats [repo] - 显示使用统计信息（工具调用、令牌、执行时间）
• cicada watch - 监视文件变更并自动重新索引
• cicada index - 使用自定义选项重新索引代码（-f/--force、--keywords、--embeddings、--watch）
• cicada index-pr - 为 PR 归属信息建立索引
• cicada run [tool] - 直接通过 CLI 执行任意一个 MCP 工具
• cicada agents install - 将 Claude Code Agent 安装到 ./.claude/ 目录
• cicada link [parent_dir] - 将当前仓库链接到已有索引
• cicada clean - 从文件夹中彻底移除 CICADA 集成及所有设置

向助手提问：

# Elixir
"Show me the functions in MyApp.User"
"Where is authenticate/2 called?"

# Python
"Show me the AuthService class methods"
"Where is login() used in the codebase?"

# Both languages
"Find code related to API authentication"

隐私与安全

• **100% 本地运行：**解析和索引都在你的计算机上进行；不会访问外部。
• **无遥测：**CICADA 不会收集使用情况数据或任何遥测信息。
• **只读工具：**MCP 端点只读取索引；无法修改你的仓库。
• **可选的 GitHub 访问：**PR 功能依赖 gh 和你现有的 OAuth 令牌。
• 数据布局：

  ~/.cicada/projects/<repo_hash>/
  ├─ index.json      # modules, functions, call sites, metadata
  ├─ config.yaml     # indexing options + mode
  ├─ hashes.json     # incremental indexing cache
  └─ pr_index.json   # optional PR metadata + reviews
  

  你的仓库只会新增一个编辑器配置（.mcp.json、.cursor/mcp.json、.vscode/settings.json、.gemini/settings.json、.codex/mcp.json 或 .opencode.json）。

面向开发者

在编辑器中接入一次 CICADA，即可让每个助手会话都继承相关上下文。

安装与配置

cd /path/to/project
cicada claude   # or cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode / cicada zed

启用 PR 归属信息（可选）

brew install gh    # or apt install gh
gh auth login
cicada index-pr .     # incremental
cicada index-pr . --clean   # full rebuild

这样就能提出“哪一个 PR 引入了第 42 行？”或“审查者对 billing.ex 有什么看法？”之类的问题。

使用监视模式自动重新索引

启动 MCP 服务时添加 --watch 标志，即可在文件变更时自动重新索引：

** .mcp.json**

{
  "mcpServers": {
    "cicada": {
      "command": "cicada-mcp",
      "args": ["--watch"],
      "env": {
        "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>"
      }
    }
  }
}

启用监视模式后：

• 单独的进程会监视 .ex、.exs（Elixir）和 .py（Python）文件的变更
• 文件变更后会自动重新索引（增量式，速度快）
• 2 秒的防抖时间可避免快速编辑时过度重新索引
• MCP 服务停止时，监视进程也会自动停止
• 排除的目录：deps、_build、node_modules、.git、assets、priv、.venv、venv

CLI 速查表

**注意：**语言检测会自动进行——CICADA 会自动检测 Elixir（mix.exs）和 Python（pyproject.toml）项目。

故障排除

cicada index /path/to/project

cicada index .

# Install GitHub CLI
brew install gh  # macOS
sudo apt install gh  # Ubuntu
# or visit https://cli.github.com/

# Authenticate
gh auth login

# Index PRs
cicada index-pr

cicada index-pr --clean

# Re-index with keyword extraction
cicada index .  # or --keywords

cat ~/.cicada/projects/<hash>/config.yaml
# Should show:
# indexing:
#   mode: keywords

更多详情：PR 索引、增量索引。

# Ensure .venv is excluded
echo "/.venv/" >> .gitignore

# Use keywords mode for quickest indexing
cicada index --keywords .

面向 AI 助手

CICADA 提供 7 个专用 MCP 工具，旨在高效探索 Elixir、Python 和 Erlang 代码库。

🧭 应该使用哪个工具？

想看看这些工具的实际用法？ 请查看完整工作流示例，其中包含专业技巧和真实场景。

核心工具

query - 智能代码发现（从这里开始）

• 自动识别关键词与模式
• 筛选条件：scope（公开／私有）、recent（最近 14 天）、filter_type（模块／函数）、match_source（文档／字符串）
• 返回代码片段，并智能建议后续步骤
• 使用 path_pattern 按位置筛选

search_module - 深入分析模块

• 查看完整 API：函数、签名、规格和文档
• 对于 Python：显示类及其方法数量和签名
• 对于 Elixir：以元数表示法显示函数
• 双向分析：
  • what_calls_it=true → 查看哪些地方使用了此模块（影响分析）
  • what_it_calls=true → 查看此模块依赖的内容
• 支持通配符（Elixir：MyApp.*，Python：api.handlers.*）和 OR 模式（MyApp.User|MyApp.Post）
• 按可见性筛选（公开／私有／全部）

search_function - 函数使用情况跟踪

• 查找定义及所有调用位置
• what_calls_it=true（默认）→ 查看所有调用方
• what_it_calls=true → 查看所有依赖项
• 使用 include_usage_examples=true 包含代码示例
• 按 usage_type 筛选：源代码、测试或全部

Git 历史（统一工具）

git_history - 一个工具即可执行所有 Git 操作

• 单行：git_history("file.ex", start_line=42) → 代码归属信息 + PR
• 行范围：git_history("file.ex", start_line=40, end_line=60) → 分组的代码归属信息
• 函数跟踪：git_history("file.ex", function_name="create_user") → 演变历史
• 文件历史：git_history("file.ex") → 所有 PR／提交
• 时间筛选：recent=true（14 天内）、recent=false（超过 14 天）、recent=null（全部）
• 作者筛选：author="john"
• 若有 PR 索引，则自动集成

其他工具

expand_result - 深入查看查询结果

• 自动识别模块或函数
• 显示完整详情和使用示例
• 配置要包含的内容：代码、依赖项、调用方
• 便捷地封装 search_module 和 search_function

query_jq - 高级索引查询

• 直接对索引执行 jq 查询
• 使用 | schema 发现架构
• 紧凑（默认）或美化输出
• 大型结果的采样模式

详细参数和输出格式：MCP_TOOLS_REFERENCE.md。

节省 Token 的响应

所有工具均返回结构化的 Markdown／JSON 片段（签名、调用位置、PR 元数据），而非完整文件，从而精简提示词。

v0.5.1 新增： 所有工具现在默认使用紧凑输出，以尽量减少 Token 用量。使用 verbose=true 可查看包含完整文档和规格的详细输出。

文档

• Codebook – 完整的功能参考和用户指南
• 工作流 – 串联使用多个工具的真实示例
• 安装 – 所有编辑器的分步设置指南
• 贡献指南 – 开发指南和架构说明
• CHANGELOG.md – 发行说明

深入阅读：

• 关键词提取分析 – 语义搜索内部机制
• PR 索引 – GitHub 集成详情
• MCP 工具调用基准测试 – Token／时间基准测试
• 工具可发现性 – UX 改进研究

路线图

当前状态

已可用于生产环境：

• ✅ Elixir（tree-sitter）
• ✅ Python（SCIP）
• ✅ TypeScript（SCIP）
• ✅ JavaScript（SCIP）
• ✅ Rust（SCIP）

Beta 版：

• 🚧 Erlang（tree-sitter）
• 🚧 Go（SCIP）
• 🚧 Java/Kotlin/Scala（SCIP）
• 🚧 C/C++（SCIP）
• 🚧 Ruby（SCIP）
• 🚧 C#/Visual Basic（SCIP）
• 🚧 Dart（SCIP）
• 🚧 PHP（SCIP）

与其他方案的比较

选择 CICADA 的情况： 你希望优先在本地运行，同时获得丰富的 Git 上下文（PR 归属信息、blame、函数演进跟踪）和高效的令牌使用。

选择 Serena 的情况： 你需要通过 LSP 编辑代码，并且可以接受较高的资源使用量。

选择 Codicil 的情况： 你有一个 Elixir 项目，并且偏好由大模型驱动的语义摘要（仅支持 Elixir）。

参与贡献

git clone https://github.com/wende/cicada.git
cd cicada
uv sync
pytest

提交 PR 前：

• 运行 black cicada tests
• 确保测试和覆盖率检查通过（pytest --cov=cicada --cov-report=term-missing）
• 如果行为有变化，请更新文档

我们欢迎提交以下方面的 issue/PR：

• 新的语言语法
• 改进工具输出
• 更完善的入门文档和教程

许可证

MIT – 参见 LICENSE。