Aidex

AiDex

AI コーディングエージェントのための永続的な頭脳です。

AiDex は、AI コーディングアシスタントにメモリ、セマンティック検索、リアルタイムテレメトリーを提供する MCP サーバーです。ローカルファーストで、特定のモデルに依存しません。Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilot など、MCP 対応のあらゆる AI アシスタントで動作します。

3 つの柱

🧠 メモリ — タスク、メモ、セッションメモはチャットをまたいで保持されます。履歴の自動記録、スケジュールされたタスク、セッションをまたぐ継続性を備えています。今日重要だったことを、AI が明日も把握できます。

🔍 検索 — 3 つのモードがあります。exact（識別子）、semantic（概念）、hybrid（両方を RRF で統合）。コード、ドキュメント、ワークスペース項目をひとつのランキングにまとめて埋め込みます。プロジェクト横断で、すべてのリポジトリを 1 回のクエリで検索できます。オプションの LLM レイヤーにより、英語以外のクエリの翻訳や、検索結果の再ランキングも可能です。

🌐 テレメトリー — LogHub は SDK を使わず、HTTP 経由であらゆるアプリからリアルタイムのログを受信します。AI はコードが実際に何をしているかを監視します。コードが何を述べているかだけではありません。ビューアーにリアルタイムでストリーミングされます。

14言語 — C#、TypeScript、JavaScript、Rust、Python、C、C++、Java、Go、PHP、Ruby、HCL/Terraform、Kotlin、Swift — に加え、Astroのフロントマターにも対応

# Find where "PlayerHealth" is defined — 1 call, ~50 tokens
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# All methods in a file — without reading the whole file
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# What changed in the last 2 hours?
aidex_query({ term: "render", modified_since: "2h" })

# Search across ALL your projects at once
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ Found in: LibWebAppGpu (3 hits), DebugViewer (1 hit)

# Leave a note for your next session
aidex_note({ path: ".", note: "Test the parser fix after restart" })

# Create a task while working
aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", priority: 1, tags: "bug" })

目次

• 内容
• セマンティック検索とLLMレイヤー 🆕
• 問題点
• 解決策
• Grepだけでは不十分な理由
• 仕組み
• 機能
• 対応言語
• クイックスタート
• 利用可能なツール
• 時間ベースのフィルタリング
• プロジェクト構成
• セッションメモ
• タスクバックログ
• グローバル検索
• AIガイドライン
• ログハブ — 汎用ロギング
• デバッグダッシュボード
• スクリーンショット — LLM向けに最適化
• インタラクティブViewer
• CLIの使用方法
• パフォーマンス
• テクノロジー
• コントリビューション
• ライセンス

セマンティック検索とLLMレイヤー

v2.0では、ローカルで実行する埋め込みによるセマンティック検索が追加されました。AIは正確な識別子がわからなくても、関数を見つけられます。

3つのモード — 質問に合ったツールを選択

埋め込み対象

• コード — すべてのメソッドと型を、3 層のチャンク分割方式で処理します（シグネチャ＋ドキュメントコメント＋重み付けされた識別子の集合）
• ドキュメント — Markdown のセクション（README、CHANGELOG、docs/、plan ファイル）を、見出しの境界で分割します
• ワークスペース — タスク、タスクログ、セッションメモ、アーカイブ済みのメモ履歴

あらゆる種類を、ひとつのランキングで検索できます。たとえば 「外部プログラムからログを書き込む方法」 というクエリでは、README の ## Log Hub セクションが最初に表示され、次に commands/log.ts の log メソッド、さらに関連するタスクが表示されます。

セットアップ

// Enable embeddings on a project (one-time, ~30s for AiDex itself, cached afterwards)
aidex_init({ path: ".", embeddings: true })

// Search
aidex_search({ query: "how do we batch requests to the LLM", path: "." })
aidex_search({ query: "retry with backoff", scope: "all" })  // across every embedded project

または、Viewer の Settings タブ（aidex_settings({ path: ".", open: true })）を使います。埋め込み、LLM プロバイダー、モデル、プライバシー切り替えの設定を変更できます。

オプションの LLM レイヤー

Anthropic／OpenAI／OpenRouter／Ollama／HuggingFace の API キーを設定すると、AiDex で次のことができます。

• 翻訳 — 英語以外のクエリを翻訳します。「wie speichere ich Logs lokal」から適切なコードを見つけられます
• 拡張 — あいまいなクエリを 2～4 個の具体的なサブクエリに展開します（RRF で統合）
• 再ランキング — 上位 N 件の検索候補を再ランキングします

プライバシー切り替え llm_send_code はデフォルトで オフ です。送信されるのは入力したクエリとメタデータ（パス、名前、アンカー）だけです。コード本体はローカルに留まります。プロジェクトごとに設定でき、Settings で簡単に確認できます。

ローカルファースト：純粋な埋め込みだけで完全にオフライン動作します。LLM レイヤーはオプトイン方式で、必須ではありません。

課題

AI アシスタントがコードを検索するたびに、次のことが起こります。

• grep — 数千ものファイルを検索し、数百件の結果がコンテキストにあふれます
• 読み込み — 構造を把握するためにファイルを次々と読み込み、コンテキストをさらに消費します
• 忘却 — セッションが終了するとすべて忘れてしまい、最初からやり直しになります

「X はどこで定義されていますか？」という質問ひとつで、2,000 トークン以上を消費することがあります。これを 10 回繰り返すと、ナビゲーションだけでコンテキストの半分を使い切ってしまいます。

解決策

一度インデックスを作成すれば、何度でも検索できます。

# Before: grep flooding your context
AI: grep "PlayerHealth" → 200 hits in 40 files
AI: read File1.cs, File2.cs, File3.cs...
→ 2000+ tokens consumed, 5+ tool calls

# After: precise results, minimal context
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ ~50 tokens, 1 tool call

結果：コードのナビゲーションに使用するコンテキストを 50～80％削減できます。

grep だけではだめなのですか？

grep の実際のコスト：grep の結果にはすべて、周辺のコンテキストが含まれます。大規模なプロジェクトで User を検索すると、コメント、文字列、部分一致など、何百件もの結果が返されます。AI はそれらをすべて読み込むため、ノイズにコンテキストトークンを消費します。

AiDex は識別子をインデックス化します：Tree-sitter を使ってコードを実際に解析します。User を検索すると、「user」に言及するすべてのコメントではなく、クラス定義、メソッドのパラメーター、変数宣言が見つかります。

仕組み

1. プロジェクトのインデックスを一度作成します（ファイル 1,000 件あたり約 1 秒）

   aidex_init({ path: "/path/to/project" })
   

2. AI は grep の代わりにインデックスを検索します

   aidex_query({ term: "Calculate", mode: "starts_with" })
   → All functions starting with "Calculate" + exact line numbers
   
   aidex_query({ term: "Player", modified_since: "2h" })
   → Only matches changed in the last 2 hours
   

3. ファイル全体を読み込まずに概要を取得できます

   aidex_signature({ file: "src/Engine.cs" })
   → All classes, methods, and their signatures
   

インデックスは .aidex/index.db（SQLite）に保存されます。高速で、ポータブルで、外部依存関係はありません。

機能

• Tree-sitter による解析：正規表現ではなく、実際にコードを解析します。識別子をインデックス化し、キーワードやノイズは無視します
• 検索あたり約 50 トークン：grep の 2,000 トークン以上と比べて、AI が実際の作業にコンテキストを使えるようになります
• 永続インデックス：セッション間で保持されるため、再スキャンや再読み込みは不要です
• 差分更新：プロジェクト全体ではなく、変更後に個別ファイルを再インデックス化できます
• 時間ベースのフィルタリング：直近 1 時間、1 日、1 週間に変更されたものを検索できます
• 自動クリーンアップ：除外されたファイル（ビルド出力など）はインデックスから自動的に削除されます
• 依存関係ゼロ：WAL モードの SQLite を使用。単一ファイルで、高速かつポータブルです

対応言語

クイックスタート

前提条件

• Node.js ≥ 20（node --version で確認）
  • macOS：brew install node または nvm install 20 && nvm use 20
  • Linux：パッケージマネージャーまたは nvm を使用してください
  • Windows：nodejs.org
  • nvm を使用している場合、リポジトリには .nvmrc が含まれています。nvm use を実行すると、適切なバージョンが自動的に選択されます。

1. インストール

npm install -g aidex-mcp

これで完了です。 インストール後にセットアップが自動的に実行され、インストール済みの AI クライアント（Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilot）を検出し、AiDex を MCP サーバーとして登録します。また、AI の設定ファイル（~/.claude/CLAUDE.md、~/.gemini/GEMINI.md）に使用方法の説明を追加します。

セットアップを手動で再実行するには：aidex setup | 登録を解除するには：aidex unsetup | 自動セットアップをスキップするには：AIDEX_NO_SETUP=1 npm install -g aidex-mcp

2. または AI アシスタントに手動で登録する

Claude Code の場合（~/.claude/settings.json または ~/.claude.json）：

{
  "mcpServers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex",
      "env": {}
    }
  }
}

Claude Desktop の場合（Windows では %APPDATA%/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

注： コマンド名として aidex と aidex-mcp のどちらも使用できます。

重要： 設定内のサーバー名によって、MCP ツールのプレフィックスが決まります。上記のように "aidex" を使用してください。これにより、aidex_query、aidex_signature などのツール名が使用できます。別の名前（例："codegraph"）を使用すると、それに応じてプレフィックスが変わります。

Gemini CLI の場合（~/.gemini/settings.json）：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

VS Code Copilot の場合（コマンドパレットで MCP: Open User Configuration を実行）：

{
  "servers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex"
    }
  }
}

その他の MCP クライアントの場合：MCP サーバーの設定については、お使いのクライアントのドキュメントを参照してください。

3. AI に実際に使わせる

AI の指示に追加してください（例：Claude Code の場合は ~/.claude/CLAUDE.md、またはお使いの AI クライアントの同等のファイル）。これにより、grep の代わりに AiDex をいつ、どのように使うかを AI に伝えます。

## AiDex - Persistent Code Index (MCP Server)

AiDex provides fast, precise code search through a pre-built index.
**Always prefer AiDex over Grep/Glob for code searches.**

### REQUIRED: Before using Grep/Glob/Read for code searches

コードを検索しますか？ ├── .aidex/ がある → 停止！ 代わりに AiDex を使用 ├── .aidex/ がない → aidex_init を実行（確認不要）、その後 AiDex を使用 └── 設定／ログ／テキスト → Grep/Read を使用しても問題ありません

**NEVER do this when .aidex/ exists:**
- ❌ `Grep pattern="functionName"` → ✅ `aidex_query term="functionName"`
- ❌ `Grep pattern="class.*Name"` → ✅ `aidex_query term="Name" mode="contains"`
- ❌ `Read file.cs` to see methods → ✅ `aidex_signature file="file.cs"`
- ❌ `Glob pattern="**/*.cs"` + Read → ✅ `aidex_signatures pattern="**/*.cs"`

### Session-Start Rule (REQUIRED — every session, no exceptions)

1. Call `aidex_session({ path: "<project>" })` — detects external changes, auto-reindexes
2. If `.aidex/` does NOT exist → run `aidex_init` automatically (don't ask)
3. If a session note exists → **show it to the user** before continuing
4. **Before ending a session:** always leave a note about what to do next

### Question → Right Tool

| Question | Tool |
|----------|------|
| "Where is X defined?" | `aidex_query term="X"` |
| "Find anything containing X" | `aidex_query term="X" mode="contains"` |
| "All functions starting with X" | `aidex_query term="X" mode="starts_with"` |
| "What methods does file Y have?" | `aidex_signature file="Y"` |
| "Explore all files in src/" | `aidex_signatures pattern="src/**"` |
| "Project overview" | `aidex_summary` + `aidex_tree` |
| "What changed recently?" | `aidex_query term="X" modified_since="2h"` |
| "What files changed today?" | `aidex_files path="." modified_since="8h"` |
| "Have I ever written X?" | `aidex_global_query term="X" mode="contains"` |
| "Which project has class Y?" | `aidex_global_signatures term="Y" kind="class"` |
| "All indexed projects?" | `aidex_global_status` |

### Search Modes

- **`exact`** (default): Finds only the exact identifier — `log` won't match `catalog`
- **`contains`**: Finds identifiers containing the term — `render` matches `preRenderSetup`
- **`starts_with`**: Finds identifiers starting with the term — `Update` matches `UpdatePlayer`, `UpdateUI`

### All Tools (30)

| Category | Tools | Purpose |
|----------|-------|---------|
| Search & Index | `aidex_init`, `aidex_query`, `aidex_update`, `aidex_remove`, `aidex_status` | Index project, search identifiers (exact/contains/starts_with), time filter |
| Signatures | `aidex_signature`, `aidex_signatures` | Get classes + methods without reading files |
| Overview | `aidex_summary`, `aidex_tree`, `aidex_describe`, `aidex_files` | Entry points, file tree, file listing by type |
| Cross-Project | `aidex_link`, `aidex_unlink`, `aidex_links`, `aidex_scan` | Link dependencies, discover projects |
| Global Search | `aidex_global_init`, `aidex_global_query`, `aidex_global_signatures`, `aidex_global_status`, `aidex_global_refresh` | Search across ALL projects |
| Guidelines | `aidex_global_guideline` | Persistent AI instructions & conventions (key-value, global) |
| Sessions | `aidex_session`, `aidex_note` | Track sessions, leave notes (with searchable history) |
| Tasks | `aidex_task`, `aidex_tasks` | Built-in backlog with priorities, tags, summaries, auto-logged history, scheduled/recurring tasks |
| Log Hub | `aidex_log` | Universal log receiver — any program sends logs via HTTP, AI queries them, live in Viewer |
| Screenshots | `aidex_screenshot`, `aidex_windows` | Screen capture with LLM optimization (scale + color reduction, no index needed) |
| Viewer | `aidex_viewer` | Interactive browser UI with file tree, signatures, tasks, and live logs |

**14 languages:** C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — plus Astro frontmatter

### Session Notes

Leave notes for the next session — they persist in the database:

aidex_note({ path: ".", note: "再起動後に修正をテストする" }) # 書き込み aidex_note({ path: ".", note: "エッジケースも確認する", append: true }) # 追記 aidex_note({ path: "." }) # 読み取り aidex_note({ path: ".", search: "parser" }) # 履歴を検索 aidex_note({ path: ".", clear: true }) # 消去

- **Before ending a session:** automatically leave a note about next steps
- **User says "remember for next session: ..."** → write it immediately

### Task Backlog

Track TODOs, bugs, and features right next to your code index:

aidex_task({ path: ".", action: "create", title: "バグを修正", priority: 1, tags: "bug" }) aidex_task({ path: ".", action: "update", id: 1, status: "done" }) aidex_task({ path: ".", action: "log", id: 1, note: "根本原因を特定" }) aidex_tasks({ path: ".", status: "active" })

スケジュールされたタスクと定期タスク

aidex_task({ path: ".", action: "create", title: "Check PR status", due: "3d", interval: "3d", task_action: "gh pr list" })

Priority: 1=high, 2=medium, 3=low | Status: `backlog → active → done | cancelled`

### Global Search (across all projects)

aidex_global_init({ path: "/path/to/all/repos" }) # スキャンして登録 aidex_global_init({ path: "...", index_unindexed: true }) # + 小規模プロジェクトを自動でインデックス化 aidex_global_query({ term: "TransparentWindow", mode: "contains" }) # すべてのプロジェクトを検索 aidex_global_signatures({ term: "Render", kind: "method" }) # すべてのプロジェクトからメソッドを検索 aidex_global_status({ sort: "recent" }) # すべてのプロジェクトを一覧表示

### Screenshots

aidex_screenshot() # 全画面 aidex_screenshot({ mode: "active_window" }) # アクティブウィンドウ aidex_screenshot({ mode: "window", window_title: "VS Code" }) # 特定のウィンドウ aidex_screenshot({ scale: 0.5, colors: 2 }) # 白黒、半分のサイズ（LLM に最適） aidex_screenshot({ colors: 16 }) # 16 色（UI を読みやすく表示） aidex_windows({ filter: "chrome" }) # ウィンドウタイトルを検索

No index needed. Returns file path → use `Read` to view immediately.

**LLM optimization strategy:** Always start with aggressive settings, then retry if unreadable:
1. First try: `scale: 0.5, colors: 2` (B&W, half size — smallest possible)
2. If unreadable: retry with `colors: 16` (adds shading for UI elements)
3. If still unclear: `scale: 0.75` or omit `colors` for full quality
4. **Remember** what works for each window/app during the session — don't retry every time.

4. プロジェクトをインデックス化する

AI に次のように依頼します： 「AiDex でこのプロジェクトをインデックス化してください」

または、AI チャットで手動で実行します：

aidex_init({ path: "/path/to/your/project" })

利用可能なツール

時間による絞り込み

modified_since と modified_before を使って、最近変更されたものを追跡します：

aidex_query({ term: "render", modified_since: "2h" })   # Last 2 hours
aidex_query({ term: "User", modified_since: "1d" })     # Last day
aidex_query({ term: "API", modified_since: "1w" })      # Last week

対応形式：

• 相対指定：30m（分）、2h（時間）、1d（日）、1w（週）
• ISO 日付：2026-01-27 または 2026-01-27T14:30:00

「過去 1 時間で何を変更しましたか？」 といった質問に最適です。

プロジェクト構成

AiDex は、コードだけでなくプロジェクト内のすべてのファイルをインデックス化するため、構成を検索できます：

aidex_files({ path: ".", type: "config" })  # All config files
aidex_files({ path: ".", type: "test" })    # All test files
aidex_files({ path: ".", pattern: "**/*.md" })  # All markdown files
aidex_files({ path: ".", modified_since: "30m" })  # Changed this session

ファイルの種類：code、config、doc、asset、test、other、dir

modified_since を使うと、このセッションで変更されたファイルを検索できます。「何を編集しましたか？」 といった質問に最適です。

セッションメモ

次のセッションに向けたリマインダーを残しましょう。チャット間でコンテキストを失うことはもうありません。

aidex_note({ path: ".", note: "Test the glob fix after restart" })  # Write
aidex_note({ path: ".", note: "Also check edge cases", append: true })  # Append
aidex_note({ path: "." })                                              # Read
aidex_note({ path: ".", clear: true })                                 # Clear

メモの履歴（v1.10）：上書きまたは消去された古いメモは、自動的にアーカイブされます。過去のメモを閲覧・検索できます。

aidex_note({ path: ".", history: true })                    # Browse archived notes (shows summaries)
aidex_note({ path: ".", search: "parser" })                 # Search note history (searches summaries too)
aidex_note({ path: ".", history: true, limit: 5 })          # Last 5 archived notes

メモの要約（v1.15）：メモを作成・消去するときにsummaryを指定すると、アーカイブされたメモに一文の説明が追加されます。履歴には、省略された本文の代わりに要約が表示されます。

aidex_note({ path: ".", note: "New focus", summary: "Previous session: finished parser refactoring" })

ユースケース：

• セッションを終了する前に：「次回はXをテストすることを覚えておいて」
• AI による自動リマインダー：再起動後に確認することを保存
• 引き継ぎメモ：設定ファイルを編集せずに、次のセッション向けのコンテキストを残す
• 過去のセッションを検索：「パーサーについて何をしたっけ？」

メモはSQLiteデータベース（.aidex/index.db）に保存され、期限なく保持されます。

タスクのバックログ

プロジェクトのタスクをコードインデックスのすぐそばで管理できます。JiraもTrelloも、コンテキストの切り替えも不要です。

aidex_task({ path: ".", action: "create", title: "Fix parser bug", priority: 1, tags: "bug", summary: "Parser crashes on nested generics in C#" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause: unbounded buffer" })
aidex_tasks({ path: ".", status: "active" })

予約済みタスクと定期タスク

タスクには期限と繰り返し間隔を設定できます。期限切れのタスクは、すべてのプロジェクトを対象に、各セッションの開始時に報告されます。

# One-shot: remind in 3 days
aidex_task({ path: ".", action: "create", title: "Review PR", due: "3d", task_action: "Check if PR was submitted" })

# Recurring: check every week
aidex_task({ path: ".", action: "create", title: "Check dependencies", due: "1w", interval: "1w", task_action: "npm outdated" })

# Auto-execute: runs the action automatically when due
aidex_task({ path: ".", action: "create", title: "Refresh stats", due: "1d", interval: "1d", auto_go: true })

期限の形式： 相対指定（"30m"、"2h"、"3d"、"1w"）またはISO日付（"2026-04-10"）

aidex_sessionが呼び出されるたびに、タスクスケジューラーは~/.aidex/global.dbを確認し、すべてのプロジェクトの期限到来タスクを調べます。別のプロジェクトで作業している場合も対象です。定期タスクは、実行されるたびに期限が自動的に更新されます。

機能：

• 要約：タスクごとに一文の目次を表示。詳細を読まずにバックログを確認できます
• 優先度：🔴 高、🟡 中、⚪ 低
• ステータス：backlog → active → done | cancelled
• タグ：タスクを分類（bug、feature、docsなど）
• 履歴ログ：ステータスの変更はすべて自動で記録され、手動のメモも追加できます
• スケジュール設定：期限、繰り返し間隔、アクション、すべてのプロジェクトでの自動実行
• ビューアー連携：ブラウザービューアーのタブでタスクをリアルタイムに表示
• 永続化：タスクはセッション間で保持され、.aidex/index.dbに保存されます

AI アシスタントは、作業中にタスクを作成し（「パーサーにバグを見つけたので、バックログに追加して」）、進捗を追跡して、次のセッションで前回の続きから作業できます。

グローバル検索

インデックス化されたすべてのプロジェクトを一度に検索します。「透明なウィンドウを書いたことはあったっけ？」や「このアルゴリズムはどこで使った？」といった検索に最適です。

セットアップ

aidex_global_init({ path: "Q:/develop" })                              # Scan & register
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })      # Skip external repos
aidex_global_init({ path: "Q:/develop", index_unindexed: true })       # Auto-index all found projects
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })  # With browser progress UI

プロジェクトディレクトリをスキャンし、AiDexでインデックス化されたすべてのプロジェクトをグローバルデータベース（~/.aidex/global.db）に登録します。また、プロジェクトマーカー（.csproj、package.json、Cargo.tomlなど）を検出し、インデックス化されていないプロジェクトが見つかると報告します。

index_unindexed: trueを指定すると、検出されたプロジェクトのうち、コードファイルが500個以下のものも自動的にインデックス化されます。規模の大きいプロジェクトは、ユーザーが判断できるよう別途一覧表示されます。show_progress: trueを追加すると、ブラウザーで進行状況をリアルタイム表示するUIが開きます（http://localhost:3334）。

検索

aidex_global_query({ term: "TransparentWindow" })                      # Exact match
aidex_global_query({ term: "transparent", mode: "contains" })          # Fuzzy search
aidex_global_signatures({ term: "Render", kind: "method" })            # Find methods
aidex_global_signatures({ term: "Player", kind: "class" })             # Find classes

仕組み

• SQLiteのATTACH DATABASEを使ってプロジェクトのデータベースを直接クエリするため、データのコピーはありません
• 結果はメモリ内にキャッシュされるため、繰り返しのクエリを高速に実行できます（TTLは5分）
• SQLiteのアタッチ上限を守るため、プロジェクトを8件ずつ処理します
• 各プロジェクトは、それぞれの.aidex/index.dbを唯一の信頼できる情報源として保持します
• 自動重複排除：サブプロジェクトを含む親プロジェクトは自動的に除外されます（例：MyApp/Frontend/とMyApp/Backend/が別々にインデックス化されている場合、MyApp/は除外されます）

管理

aidex_global_status()                                                  # List all projects
aidex_global_status({ sort: "recent" })                                # Most recently indexed first
aidex_global_refresh()                                                 # Update stats, remove stale

AI ガイドライン

永続的なコーディング規約、レビュー用チェックリスト、AI への指示を 1 か所に保存し、すべてのプロジェクトで共有できます。

aidex_global_guideline({ action: "set", key: "review", value: "Always check: error handling, null safety, no hardcoded strings" })
aidex_global_guideline({ action: "set", key: "style", value: "Use PascalCase for classes, camelCase for methods, 4-space indent" })
aidex_global_guideline({ action: "get", key: "review" })               # Retrieve a guideline
aidex_global_guideline({ action: "list" })                             # Show all guidelines
aidex_global_guideline({ action: "list", filter: "code" })             # Filter by name
aidex_global_guideline({ action: "delete", key: "old-rule" })          # Remove a guideline

ユースケース：

• コードレビュー用チェックリスト：毎回 AI に確認してほしい項目を具体的に指示できます
• コーディング規約：チームのスタイルルールを一度保存すれば、どのプロジェクトからでも参照できます
• リリース用チェックリスト：リリースまでの手順を順を追ってまとめられます
• プロジェクトに依存しない指示：毎回同じコンテキストをセッションに貼り付ける必要はありません

ガイドラインは ~/.aidex/global.db に保存されるため、aidex_init を使わなくても、すべてのプロジェクトで利用できます。AI に「レビュー用ガイドラインを読み込んで、このファイルに適用してください」と指示します。

Log Hub — 汎用ロギング

あらゆるプログラムを AI アシスタントのログソースにできます。アプリが HTTP POST でログを送信し、AI が MCP 経由でログを照会すると、Viewer でリアルタイムに確認できます。依存関係は不要で、コードへの設定も必要ありません。

仕組み

Your Program ──HTTP POST──→ AiDex Log Hub (port 3335) ──→ Ring Buffer
                                        │                      │
                                        │ WebSocket             │ MCP query
                                        ↓                      ↓
                                   Viewer (Logs tab)      AI Assistant
                                   (you see live)       (queries & analyzes)

クイックスタート

1. AI が Log Hub を起動します：aidex_log({ action: "init" })
2. AI が Viewer を開きます：aidex_viewer({ path: "." }) — Logs タブにライブストリームが表示されます
3. プログラムに 1 行追加します：

// C#
await new HttpClient().PostAsJsonAsync("http://localhost:3335/log",
    new { level = "info", source = "MyApp", message = "Player spawned", data = new { x = 10, y = 20 } });

# Python
requests.post("http://localhost:3335/log", json={"level": "info", "source": "MyApp", "message": "Done"})

// JavaScript
fetch("http://localhost:3335/log", {
    method: "POST", headers: {"Content-Type": "application/json"},
    body: JSON.stringify({level: "info", source: "MyApp", message: "Started"})
});

# PowerShell
Invoke-RestMethod -Uri http://localhost:3335/log -Method POST -ContentType "application/json" -Body '{"level":"info","source":"Script","message":"Done"}'

HTTP API

フィールド： level（debug／info／warn／error）、source（アプリ名）、message（テキスト、必須）、data（任意の JSON）、timestamp（任意、ミリ秒）

機能

• リングバッファ：固定サイズのメモリ内 FIFO（デフォルトは 10,000 エントリ）。古いエントリは上書きされます
• ゼロコスト：init が呼び出されるまで、サーバーもバッファもリソースも使用しません
• 永続化：7 日後に自動クリーンアップされる SQLite ストレージを任意で使用できます（persist: true）
• 消費パターン：consume: true を指定して query すると、返されたエントリが削除されます。ポーリングに最適です
• Viewer との連携：WebSocket によるライブストリーム、レベル／ソース／テキストのフィルター、自動スクロールを備えた Logs タブ
• 送信して終了：POST するだけで完了です。サーバーが起動していない場合、POST はエラーを通知せずに失敗します

Control API — AI がアプリを 操作 できるようにします

ログとダッシュボードウィジェットは アプリ → AI に流れます。Control API はその戻りチャネル、つまり AI → アプリ です。Log Hub を依存関係ゼロの小さなコマンドバスに変え、サーバーを書かなくても AI アシスタントが実行中のプログラムを操作できるようにします。

AI がコマンドを設定し、アプリがそれをポーリングして実行し、結果を返します。

AI ──control_set {id,cmd}──→  Hub  ←──GET /control──  Your App (polls ~1s)
AI ←──control_get──── result ─ Hub  ←──POST /control── runs it, posts result + ack

• control_set { id, value } — AI（または Viewer のスライダー／スイッチ）がコントロールスロットを設定します。
• GET /control — アプリが現在のすべてのコントロール値を読み取ります。
• POST /control — アプリが結果や確認応答を書き戻します。
• POST /control/press { id } — button コントロールの押下を 1 回登録します。カウンターはハブが管理するため、複数のダッシュボードを開いていても、押下回数は上書きされず加算されます。
• control_get — AI がアプリの報告内容を読み取ります。
• POST /control/subscribe (オプション) — ポーリングの代わりにプッシュします。詳しくは以下をご覧ください。

ポーリングの代わりにプッシュ。 アプリが独自の HTTP サーバーを実行している場合、{ "port": 8080 }（ハブは送信元のアドレスにコールバックし、パスのデフォルトは /control）または完全な { "url": "http://192.168.1.50:8080/control" } を使って一度だけサブスクライブできます。必要に応じて { "ids": [...] } で対象を限定できます。その後、変更のたびに、GET /control が返すのと同じフラットな { id: value } マップが、その URL にすぐ POST されます。アイドル時のリクエストがなくなり、次のポーリングまで遅延することもありません。ハブはアプリの応答を待って処理を止めることはなく（タイムアウトは 1.5 秒、同時に実行されるリクエストは 1 件で、その間の変更は統合されるため最新の値が必ず最後に届きます）、プライベートネットワークの IP アドレスのみを呼び出し、配信に 3 回失敗するとサブスクリプションを解除します。再サブスクライブは冪等なので、いつでも実行できます。POST /control/unsubscribe { url } で解除できます。プッシュは置き換えではなく追加の機能です。安全策として、低頻度のポーリング（約 30 秒）を維持してください。ボタンカウンターがあるため、プッシュを受け損ねても問題ありません。

button の値はフラグではなく、押下カウンターです。アプリは任意の間隔でポーリングするため、「押されたかどうか」を調べるのではなく、前回確認したカウントと比較してください。値が前回より小さくなっていたら、ハブが再起動したかパネルがクリアされています。その値を採用し、何百万回も押されたと解釈しないでください。

慣例として 2 つのスロットを使えば、完全なリクエスト／レスポンスを実現できます。AI が書き込む *_cmd スロット、アプリが書き込む *_result スロット、そして各コマンドを厳密に 1 回だけ実行するための *_ack カウンターです（コマンドごとに id を増やし、アプリは処理済みの id をスキップします）。

プロトコルはこれだけです。クライアントに必要なのは、すでに使っている HTTP ライブラリだけです。

実例 — AI による Autodesk Fusion 360 の操作

約 30 行の Fusion 360 アドイン（SDK なし、urllib のみ）が GET /control をポーリングし、Fusion のメインスレッドでコマンドを実行して、結果を返します。他には何も使わず、AI アシスタントは完全な 3D 筐体をパラメトリック設計しました。スケッチ、押し出し、ヒートセットインサート付きのネジボスドーム、USB-C の切り欠き、リセット／ボタン用の穴を作成し、実際の面のジオメトリを読み戻して各ステップを検証しました。

このパターンは汎用的です。POST と GET ができるものなら、Blender、CNC コントローラー、ゲーム、ホームオートメーションハブなど、わずか数行のコードと専用サーバーなしで AI から操作できるようになります。この実装で得られた、ほかでも適用できる安全上のルールは 2 つあります。

• シングルスレッドの GUI API： ポーリングループからアプリの API に直接触れてはいけません。イベントを発行し、メインスレッドでコマンドを実行してください（これは Fusion の公式パターンです。スレッドセーフではない UI／COM API でも同様です）。
• 冪等性： 最後に処理した id を記録し、確認応答を返してください。ポーリングでは同じコマンドが繰り返し届くため、処理済みのものはスキップします。

デバッグダッシュボード

スクロールするログストリームは「いつ何が起きたか」を確認するのには適していますが、頻繁に変わる値（オーディオレベル、バッファの充填率、FPS、センサーの読み取り値）を素早く確認するには不向きです。デバッグダッシュボードはその逆で、各値に固定の場所があり、スクロールして消えることなくその場で上書きされるパネルです。Viewer の Live タブに表示され、ハードウェアモニター（MSI Afterburner / HWiNFO）のようなスタイルです。

同じ Log Hub サーバーを利用するため、追加の設定は不要です。プログラムから HTTP POST でウィジェットの更新を送信します。同じ id を再度送信すると、そのウィジェットが更新されます。

ウィジェットの種類

ウィジェットを送信する

# A single widget — id is the fixed slot, type is required on first send
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"mic","type":"plot","value":0.73,"group":"Audio","label":"Mic Level","unit":"dB"}'

# A gauge with threshold zones (green < warn < yellow < crit < red)
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"gpu_temp","type":"gauge","value":67,"min":0,"max":100,"warn":75,"crit":90,"group":"Hardware"}'

フィールド： id（必須）、type（label/progress/gauge/plot/slider/number/toggle/button、初回の送信時に必須）、value（数値、ステータス文字列、またはプロットの全フレームを表す数値配列）、group、label、unit、min、max、warn、crit、color、order。 エンドポイント： POST /panel（1 件）、POST /panels（一括）、POST /panel/clear（1 件の場合は {id}、すべての場合は空）。

ライフサイクル

• サーバーは id ごとに最新の状態を保持するため、新しく開いた Viewer や再読み込みした Viewer にダッシュボード全体がすぐに表示されます。
• 約 3 秒間更新されないカードは、グレー表示になり「古い」状態になります。
• クリアは完全なリセットで、ストアを空にします。ソースを再表示するには、type を含めたウィジェットを再度送信する必要があります（クリアされた ID への値のみの更新は無視されます）。
• バックプレッシャー対策済みです。ブラウザーの動作が遅くても、サーバーの送信キューが際限なく増えることはありません。

お試し — 組み込みデモ

すぐに実行できるデモでは、すべてのウィジェットの種類がアニメーション表示されます（オーディオ波形、各ゾーンを移動する GPU ゲージ、正弦波 → ノコギリ波 → 三角波 → 矩形波を切り替える信号ジェネレーター、レイテンシのスパイク）。

# 1. Start the Log Hub + Viewer from your AI assistant:
#      aidex_log({ action: "init" })
#      aidex_viewer({ path: "." })       → click the Live tab
# 2. Run the demo (from the AiDex repo root):
node scripts/demo-dashboard.mjs           # endless loop, Ctrl+C to stop (clears on exit)

または、Live タブの ▷ Demo ボタンを使用してください。実行コマンドがクリップボードにコピーされるので、ターミナルに貼り付けて実行します（ブラウザーからプロセスを起動することはできません）。最初のウィジェットを表示する方法であるため、ダッシュボードがまだ空でもツールバーに表示されます。scripts/demo-dashboard.ps1 は、最初に Log Hub を確認するワンコマンドランチャーです。

2 回実行すると、2 つのインスタンスが同じウィジェットを取り合い、画面がちらつきます。別のインスタンスを起動する前に、古いインスタンスを停止してください（Ctrl+C）。

スクリーンショット — LLM 向けに最適化

スクリーンショットを撮影し、LLM のコンテキスト向けに最大 95% 縮小します。一般的なスクリーンショットのサイズは約 100 KB から約 5 KB になり、画像ごとに数千トークンを節約できます。

重要な理由

AI のコンテキストで使うスクリーンショットの大半は、エラーメッセージ、ログ、UI ラベルなどのテキストを読むためのものです。そのために 1,600 万色は必要ありません。

使い方

aidex_screenshot()                                             # Full screen (full quality)
aidex_screenshot({ mode: "active_window" })                    # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ scale: 0.5, colors: 2 })                   # B&W, half size (best for text)
aidex_screenshot({ scale: 0.5, colors: 16 })                  # 16 colors (UI readable)
aidex_screenshot({ colors: 256 })                              # 256 colors (good quality)
aidex_screenshot({ mode: "region" })                           # Interactive selection
aidex_screenshot({ mode: "rect", x: 100, y: 200, width: 800, height: 600 })  # Coordinates
aidex_windows({ filter: "chrome" })                            # Find window titles

最適化パラメーター

AI アシスタントにおすすめの方法

ツールの説明により、LLM は自動的に最適化するよう指示されます。

1. 強めの設定から開始：scale: 0.5, colors: 2（可能な限り小さく）
2. 読めない場合：colors: 16 で再試行します（UI 要素に陰影を追加します）
3. まだ不明瞭な場合：scale: 0.75 またはフルカラーを試します
4. 忘れずに：セッション中は、ウィンドウ／アプリごとにうまくいった設定をキャッシュします

この方法なら、大きすぎる画像でトークンを浪費することなく、AI がアプリごとに適切な設定を学習できます。

機能

• 5つのキャプチャモード：全画面、アクティブウィンドウ、指定ウィンドウ（タイトルで指定）、範囲の対話型選択、座標ベースの矩形
• クロスプラットフォーム：Windows（PowerShell + System.Drawing）、macOS（sips + ImageMagick）、Linux（ImageMagick）
• マルチモニター：キャプチャするモニターを選択
• 遅延：キャプチャ前にN秒待機します（例：先にメニューを開く場合）
• サイズのレポート：元のサイズから最適化後のサイズへの変化と、削減率を表示
• パスの自動設定：既定では一時ディレクトリに固定ファイル名で保存
• インデックス不要：単独で動作し、.aidex/ は不要です

インタラクティブビューアー

ブラウザーでインデックス化されたプロジェクトを視覚的に確認できます：

aidex_viewer({ path: "." })

http://localhost:3333 を開くと、次の機能を利用できます：

• インタラクティブなファイルツリー - クリックしてディレクトリを展開
• ファイルシグネチャ - ファイルをクリックして型とメソッドを表示
• ライブリロード - コーディング中の変更を自動検出
• Git ステータスアイコン - 変更済み、ステージ済み、未追跡のファイルを確認
• 検索タブ - コード、ドキュメント、タスク、ノートを対象にしたセマンティック／完全一致／ハイブリッド検索と、オプションの LLM レイヤー（翻訳 + 再ランク付け）
• ライブタブ - ライブデバッグダッシュボード：固定スロットのウィジェット（プロット、ゲージ、進捗）と、実行中のプログラムを /control チャネル経由で操作するインタラクティブなスライダー、スイッチ、ボタン
• ログタブ - Log Hub からのライブログストリームとフィルター（レベル、ソース、テキスト検索）
• タスクタブ - タスクのバックログを表示・管理
• 設定タブ - 埋め込みと LLM プロバイダーを設定（プライバシー切り替えは既定でオフ）

デバッグダッシュボード — ライブで双方向

ライブタブは固定スロットを備えたライブダッシュボードです。同じ id を再度送信すると、値はスクロールして消えるのではなく、その場で更新されます。インタラクティブな slider／number／toggle／button ウィジェットはソースに値を返します（HTTP /control、または aidex_log control_set を使えば、AI から実行中のプログラムを調整することもできます）。button はフラグではなく押下カウンターを持つため、ソースが独自のペースでポーリングしていてもクリックを見逃しません。詳しいガイド：docs/loghub-panel-dashboard.md。

Controls グループには、各インタラクティブタイプが1つずつあります。スライダー、2つのトグル、そして押下カウンターが横に表示されたボタンです。さらに下へスクロールすると、複数のソースが同じダッシュボードを共有しています。ハブは値の意味を一切把握しないため、シンセサイザーのファームウェアとデモスクリプトは、互いを認識することなく共存できます：

スライダーはリアルタイムで反応します — GIFを見る：

ビューアーのその他の機能

aidex_viewer({ path: ".", action: "close" }) で閉じます

CLI の使用方法

aidex scan Q:/develop       # Find all indexed projects
aidex init ./myproject      # Index a project from command line

aidex-mcp は aidex のエイリアスとして使用できます。

パフォーマンス

技術

• パーサー：Tree-sitter - 正規表現ではなく、本格的な構文解析
• データベース：WAL モードの SQLite - 高速な単一ファイルで、設定は不要
• プロトコル：MCP - 互換性のあるあらゆる AI で動作

プロジェクト構成

.aidex/                  ← Created in YOUR project
├── index.db             ← SQLite database
└── summary.md           ← Optional documentation

AiDex/                   ← This repository
├── src/
│   ├── commands/        ← Tool implementations
│   ├── db/              ← SQLite wrapper
│   ├── parser/          ← Tree-sitter integration
│   └── server/          ← MCP protocol handler
└── build/               ← Compiled output

コミュニティ

GitHub Discussions — 質問したり、セットアップを共有したり、アイデアを提案したりできます。

コントリビューション

詳しくはCONTRIBUTING.mdをご覧ください。概要は次のとおりです。

• バグですか？ → イシューを作成
• アイデアがありますか？ → ディスカッションを開始
• 新しい言語ですか？ → src/parser/languages/ にキーワードファイルを追加し、PRを作成してください

ライセンス

MITライセンス — LICENSEをご覧ください

著者

Uwe Chalas & Claude