CICADA

CICADA

警告

⚠️ 免責事項 — 現在の AI エージェントは、このプロジェクトが構想された当時とはまったく異なる動作をします。現在のベンチマークでは、コードインテリジェンスツールを使っても最先端モデルに対する利点はほとんど、あるいはまったくありません。CICADA は開発終了しています。CICADA やその他の「コードインテリジェンス」ツールの使用はおすすめしません。

---

Code Intelligence: Contextual Analysis, Discovery, and Attribution

AI コードアシスタント向けのコンテキスト圧縮 – Elixir、Python、TypeScript、JavaScript、Rust など、17 以上の言語にわたる構造化されたトークン効率の高いアクセスを AI に提供します。

待ち時間を最大 50% 削減 · トークンを最大 70% 削減 · 説明の手間を最大 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 - すべての MCP ツールに HTTP でアクセスするための REST API サーバーを起動します
• cicada status - インデックスの状態、PR インデックス、リンクの状態、エージェントファイル、MCP 設定を表示します
• cicada stats [repo] - 使用統計（ツールの呼び出し回数、トークン数、実行時間）を表示します
• cicada watch - ファイルの変更を監視し、自動的に再インデックスします
• cicada index - カスタムオプション（-f/--force、--keywords、--embeddings、--watch）を指定してコードを再インデックスします
• cicada index-pr - PR の帰属を追跡するためにプルリクエストをインデックスします
• cicada run [tool] - 7 つの MCP ツールのいずれかを CLI から直接実行します
• cicada agents install - Claude Code のエージェントを ./.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

「42 行目を導入した PR はどれですか？」や「billing.ex についてレビュー担当者は何と言っていましたか？」といった質問ができるようになります。

ウォッチモードによる自動再インデックス

--watch フラグを付けて MCP サーバーを起動すると、ファイルの変更時に自動で再インデックスできます。

** .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 には、Elixir、Python、Erlang のコードベースを効率的に調査するために設計された、用途を絞った 7 つの MCP ツールが用意されています。

🧭 どのツールを使うべきですか？

これらのツールの実際の使い方を見たいですか？ プロのヒントや実際のシナリオを含むワークフローの完全な例をご覧ください。

コアツール

query - スマートなコード検索（最初に使うツール）

• キーワードとパターンを自動判別します
• フィルター：scope（public/private）、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）に対応しています
• 可視性（public/private/all）で絞り込みます

search_function - 関数の使用状況の追跡

• 定義とすべての呼び出し箇所を検索します
• what_calls_it=true（デフォルト）→ 呼び出し元をすべて表示します
• what_it_calls=true → すべての依存先を表示します
• include_usage_examples=true でコード例を含めます
• usage_type（source、tests、all）で絞り込みます

Git 履歴（統合ツール）

git_history - すべての Git 操作を1つのツールで実行します

• 1行：git_history("file.ex", start_line=42) → blame + PR
• 行範囲：git_history("file.ex", start_line=40, end_line=60) → blame をグループ化
• 関数の追跡：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。

トークンに配慮した応答

すべてのツールはファイル全体ではなく、構造化された Markdown／JSON のスニペット（シグネチャ、呼び出し箇所、PR メタデータ）を返すため、プロンプトを簡潔に保てます。

v0.5.1 の新機能： トークンの使用量を最小限に抑えるため、すべてのツールでコンパクト出力がデフォルトになりました。詳細なドキュメントや仕様を含む出力には、verbose=true を使います。

ドキュメント

• Codebook – 機能の完全なリファレンスとユーザーガイド
• Workflows – ツールを連携させる実践的な例
• Installation – すべてのエディター向けのステップバイステップのセットアップ手順
• Contributing – 開発ガイドラインとアーキテクチャ
• CHANGELOG.md – リリースノート

詳細情報：

• キーワード抽出分析 – セマンティック検索の内部動作
• PR のインデックス作成 – GitHub 統合の詳細
• MCP ツール呼び出しのベンチマーク – トークン／時間のベンチマーク
• ツールの見つけやすさ – UX 改善の調査

ロードマップ

現在の状況

本番環境対応済み：

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

ベータ版：

• 🚧 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 プロジェクトで、LLM を活用したセマンティックな要約を求める場合です（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 を参照してください。