Cicada

🚀 シカダ (CICADA)

CICADAは、AIコードアシスタントに構造化されたトークン効率の良いアクセスを提供し、Elixir、Python、Erlangのコードベースをコンテキスト圧縮するためのツールです。これにより、AIはより効率的にコードを分析し、より良い品質の回答を提供することができます。

🚀 クイックスタート

なぜCICADAが必要なのか？

AIコードアシスタントは、多くの場合、ブラインドサーチによってコンテキストを浪費しています。例えば、grepは必要な関数シグネチャだけでなく、ファイル全体をダンプすることがあり、実際の推論に必要なコンテキストを減らしてしまいます。CICADAは、この問題を解決するために、構造化された事前索引付けされた知識をAIに提供します。

コンテキスト圧縮アプローチ

CICADAは、生のテキストダンプではなく、構造化された事前索引付けされた知識をAIに提供します。以下は、従来の検索方法とCICADAの比較です。

✨ 主な機能

• ASTレベルの索引付け：モジュール、関数、クラスの定義とシグネチャ、仕様、ドキュメントを提供します。
• 完全な呼び出しサイトの追跡：ElixirとPythonをまたいで、エイリアス、インポート、動的参照を追跡します。
• 意味的検索：コンセプトに基づいてコードを検索でき、単なる文字列の一致ではなく、より柔軟な検索が可能です。
• Git + PRの帰属：コードが存在する理由を明らかにし、単なるコードの内容だけでなく、その背景を理解することができます。
• 未使用コードの検出：依存関係分析を使用して、安全にリファクタリングすることができます。
• 自動言語検出：ElixirとPythonの両方のコードベースでシームレスに動作します。

📦 インストール

# 1. uvをインストールする（必要な場合）
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# リポジトリ内で
cicada claude   # または: cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode

恒久的にインストールする前に試す

uvx cicada-mcp claude   # または cursor, vs

または

claude mcp add cicada uvx cicada-mcp

gemini mcp add cicada uvx cicada-mcp

codex mcp add cicada uvx cicada-mcp

インストール後の利用可能なコマンド

• cicada [claude|cursor|vs|gemini|codex|opencode] - プロジェクトごとの1コマンドでのインタラクティブなセットアップ
• cicada-mcp - MCPサーバー（エディターによって自動起動されます）
• cicada status - インデックスの状態、PRインデックス、リンクの状態、エージェントファイル、MCP設定を表示します。
• cicada stats [repo] - 使用統計（ツール呼び出し、トークン、実行時間）を表示します。
• cicada watch - ファイルの変更を監視し、自動的に再インデックス付けを行います。
• cicada index - カスタムオプション（-f/--force + --fast/--regular/--max, --watch）でコードを再インデックス付けします。
• cicada index-pr - PR帰属のためにプルリクエストをインデックス付けします。
• cicada find-dead-code - 潜在的に未使用の関数を見つけます。
• cicada run [tool] - CLIから直接7つのMCPツールのいずれかを実行します。
• 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?"

# 両言語
"Find code related to API authentication"

📚 ドキュメント

• docs/17-WORKFLOW_EXAMPLES.md
• docs/12-TOOL_DISCOVERABILITY_TASKS.md.
• CHANGELOG.md – リリースノート。
• docs/01-KEYWORD_EXTRACTION_ANALYSIS.md – 意味的検索の内部仕様。
• docs/09-PR_INDEXING.md – GitHub統合の詳細。
• docs/16-MCP_TOOL_CALL_BENCHMARKING.md – トークン/時間のベンチマーク。

🔧 技術詳細

プライバシーとセキュリティ

• 100%ローカル：解析とインデックス付けはあなたのマシン上で行われ、外部へのアクセスはありません。
• テレメトリなし：CICADAは使用状況やテレメトリを収集しません。
• 読み取り専用ツール：MCPエンドポイントはインデックスを読み取るだけで、リポジトリを変更することはできません。
• オプションのGitHubアクセス：PR機能はghと既存のOAuthトークンに依存しています。
• データレイアウト：

  ~/.cicada/projects/<repo_hash>/
  ├─ index.json      # モジュール、関数、呼び出しサイト、メタデータ
  ├─ config.yaml     # インデックス付けのオプション + キーワードのレベル
  ├─ hashes.json     # 増分インデックス付けのキャッシュ
  └─ pr_index.json   # オプションのPRメタデータ + レビュー
  

  あなたのリポジトリには、エディターの設定ファイル（.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json, または .opencode.json）が追加されるだけです。

開発者向け

インストールと設定

cd /path/to/project
cicada claude   # または cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode

PR帰属の有効化（オプション）

brew install gh    # または apt install gh
gh auth login
cicada index-pr .     # 増分
cicada index-pr . --clean   # 完全な再構築

これにより、「Which PR introduced line 42?」や「What did reviewers say about 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 --fast or --max

cat ~/.cicada/projects/<hash>/config.yaml
# Should show keyword_extraction: enabled

詳細：docs/PR_INDEXING.md, docs/08-INCREMENTAL_INDEXING.md。

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

# Use --fast tier for quicker indexing
cicada index --fast .

AIアシスタント向け

CICADAは、Elixir、Python、Erlangのコードベースを効率的に探索するために設計された7つの焦点を絞ったMCPツールを提供します。

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

これらのツールを実際に見たいですか？ Complete Workflow Examplesをチェックして、プロのヒントと実際のシナリオを確認してください。

コアツール

query - スマートなコード発見（あなたの出発点）

• キーワードとパターンを自動的に検出します。
• フィルター：scope (public/private), recent (過去14日間), filter_type (modules/functions), match_source (docs/strings)
• スマートな次のステップの提案付きのスニペットを返します。
• 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でフィルターをかけることができます：ソース、テスト、またはすべて。

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の便利なラッパーです。

find_dead_code - コードのクリーンアップ分析

• 3つの信頼度レベル（高、中、低）
• コールバックとビヘイビアのスマートな検出
• 動的な呼び出しパターンの認識
• 行番号付きのモジュールレベルのグルーピング
• テストファイルと@impl関数を除外します。

query_jq - 高度なインデックスクエリ

• インデックスに対する直接のjqクエリ
• | schemaでスキーマを発見する
• コンパクト（デフォルト）または整形された出力
• 大きな結果の場合はサンプルモード

詳細なパラメータと出力形式：MCP_TOOLS_REFERENCE.md。

トークンフレンドリーなレスポンス

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

v0.5.1の新機能：すべてのツールはデフォルトでコンパクトな出力を使用するようになり、トークンの使用量を最小限に抑えます。詳細な出力と完全なドキュメントと仕様を表示するには、verbose=trueを使用してください。

📄 ライセンス

MIT - LICENSEを参照してください。