Nexus ⚡️

AI エージェントのための、ローカル MCP ベース・コードインデックス基盤

Nexus は、AI エージェントが巨大なコードベースを効率的に理解し、正確なコンテキストを取得するための MCP (Model Context Protocol) サーバーです。 Semantic search、Exact grep search、File context 取得を 1 つのローカルインデックスに集約し、高速かつ一貫性のある検索体験を提供します。

🚀 特徴

ハイブリッド検索: LanceDB によるベクトル検索と ripgrep による高速な文字列検索を統合。
インテリジェント・チャンキング: AST 解析に基づき、関数のセマンティクスを維持したままコードを分割。
低レイテンシ: ローカル実行に特化し、ネットワーク遅延のない高速なレスポンスを実現。
ストリーミング対応: 巨大な検索結果も Streamable HTTP transport により効率的に処理。
自律的メンテナンス: ファイル監視 (Watcher) とデッドレターキュー (DLQ) による自動的なインデックス更新とリカバリ。
プロセス間排他制御・CPU負荷抑制: proper-lockfile によるファイルベースのロックで同一プロジェクトへの複数プロセス同時起動や Ollama の CPU 奪い合いを防止。さらに、Ollama への埋め込みリクエスト単位でスレッド数を制限（デフォルト 2、範囲 1〜16）し、ホストマシンのレスポンシブネスを維持します。

🛠 セットアップ

FOR HUMANS (推奨)

[!TIP] 人間は環境構築や設定を打ち間違えることがあるため、AIエージェントに丸投げすることを強く推奨します。 Gemini CLI, Claude Code, Cursor などの AI エージェントを使用している場合は、以下のプロンプトをコピーして貼り付けてください。

Install and configure Nexus. First, read the local README.md and AGENTS.md in this repository. You MUST use your interaction tool (e.g., ask_user, input) to let me choose the installation method BEFORE executing any other commands.

📝 エージェントの恒久的な設定（グローバル AGENTS.md への追記推奨）

AI エージェントが常にこの Nexus MCP を正しく、かつコンテキストを節約して使いこなせるようにするため、あなたのグローバルなエージェント指示書（例: .github/copilot-instructions.md、.cursorrules、グローバルの AGENTS.md など）に以下のガイドラインを追記することを強く推奨します。

## Nexus MCP Server Usage Guidelines

When using **Nexus MCP** tools for codebase exploration and semantic search, adhere to these instructions for optimal performance and token budget.

### 1. WHAT & WHY (Project Overview)
- **Purpose**: Nexus is a local-first code indexing and search platform for AI agents, providing hybrid semantic search, ripgrep, and AST-based context parsing.

### 2. Tool Usage Rules (Playbook)
- **Index Status**: Run `index_status` before searching. If `pipelineProgress.status === 'running'`, search results may be incomplete.
- **Search Strategy**:
  - Use `hybrid_search` for semantic queries, vague feature exploration, or architectural questions (combines vector & ripgrep via RRF).
  - Use `grep_search` to pinpoint exact symbols, class/function names, or error strings.
- **Context Budgeting**:
  - When calling `get_context`, **DO NOT** read the entire file. Always specify `startLine` and `endLine` parameters to retrieve the minimal relevant snippet to conserve context tokens.
  - If you switch branches or make massive code changes, manually call `reindex` to refresh the local LanceDB store.

### 3. Project-Specific Context
- **Local Documentation**: In repositories where Nexus is active, refer to the project-local `SPEC.md` for architecture details and `AGENTS.md` for specific development constraints, if they exist.

FOR AGENTS (AIエージェント向け手順)

あなたがターミナル操作可能なAIエージェントであるなら、まず AGENTS.md を読み込み、そこに記載された「MANDATORY PROTOCOL」に即座に従ってください。

重要要件:

ステップ0: 独断で進めず、必ずお手持ちの**ユーザー対話ツール（ask_user, input, confirm 等）**を使用して、ユーザーに以下のいずれのインストール方式を希望するか確認してください。
PATの扱い: 「ソースからビルド」を選択した場合、GitHub PAT (Personal Access Token) は不要です。bootstrap スクリプトが自動的に認証問題を回避するように設計されています。
秘匿情報の保護: チャット内でユーザーにトークンの直接入力を求めることは禁止されています。

選択された方式に従って、AGENTS.md に集約されている詳細な手順を自律的に遂行してください。

より詳細な運用方法については AGENTS.md を参照してください。

💡 運用ガイドライン (Playbook)

インデックス状態の確認: 作業開始前に必ず index_status を呼び出し、インデックス構築が完了しているか（pipelineProgress.status === 'idle'）を確認してください。
検索の使い分け:
- 曖昧な探索・関連箇所の特定: hybrid_search を最優先で使用してください。セマンティック検索と ripgrep が融合され、最適な結果が得られます。
- 特定のシンボルやコード断片の検索: grep_search を使用してください。特定のクラス名、関数定義、エラーメッセージなどをピンポイントで検出できます。
コンテキスト取得: get_context でファイル全体を読み込むとLLMのコンテキストウィンドウを圧迫します。極力、必要な行範囲（startLine 〜 endLine）を絞り込んで部分的に取得してください。
インデックスの鮮度: 大規模なファイル変更や git checkout によるブランチ切り替えの後は、reindex を呼び出してインデックスを手動で更新することを強く推奨します。

設定が必要な場合は、プロジェクトルートに .nexus.json を作成してください。

🛠 MCP 設定例 (Claude Desktop / Gemini CLI)

各エージェントの設定ファイル（例: claude_desktop_config.json）の mcpServers セクションに以下を追加してください。

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus/dist/bin/nexus.js"],
      "env": {
        "NEXUS_STORAGE_ROOT_DIR": "/path/to/your/project/.nexus"
      }
    }
  }
}

📖 使い方

ダッシュボード (TUI) の起動

Nexus サーバーが起動している状態で、以下のコマンドを実行すると、ターミナル上でリアルタイムなインデックス状態やキューの監視が可能なダッシュボードが開きます。

# グローバルインストールされている場合
nexus dashboard

# ポート番号(指定時はそのポートを使用、未指定時は自動検出)や更新間隔(デフォルト: 2000ms, 最小: 1000ms)を指定する場合
nexus dashboard --port 9470 --interval 3000

# リポジトリ内から実行する場合
npx tsx src/bin/nexus.ts dashboard --port 9470

[!TIP] サーバー側で NEXUS_METRICS_PORT を指定して起動している場合は、ダッシュボード起動時にも --port で同じポート番号を指定してください。

Nexus ⚡️

AI エージェントのための、ローカル MCP ベース・コードインデックス基盤

🚀 特徴

ハイブリッド検索: LanceDB によるベクトル検索と ripgrep による高速な文字列検索を統合。
インテリジェント・チャンキング: AST 解析に基づき、関数のセマンティクスを維持したままコードを分割。
低レイテンシ: ローカル実行に特化し、ネットワーク遅延のない高速なレスポンスを実現。
ストリーミング対応: 巨大な検索結果も Streamable HTTP transport により効率的に処理。
自律的メンテナンス: ファイル監視 (Watcher) とデッドレターキュー (DLQ) による自動的なインデックス更新とリカバリ。
プロセス間排他制御・CPU負荷抑制: proper-lockfile によるファイルベースのロックで同一プロジェクトへの複数プロセス同時起動や Ollama の CPU 奪い合いを防止。さらに、Ollama への埋め込みリクエスト単位でスレッド数を制限（デフォルト 2、範囲 1〜16）し、ホストマシンのレスポンシブネスを維持します。

🛠 セットアップ

FOR HUMANS (推奨)

[!TIP] 人間は環境構築や設定を打ち間違えることがあるため、AIエージェントに丸投げすることを強く推奨します。 Gemini CLI, Claude Code, Cursor などの AI エージェントを使用している場合は、以下のプロンプトをコピーして貼り付けてください。

Install and configure Nexus. First, read the local README.md and AGENTS.md in this repository. You MUST use your interaction tool (e.g., ask_user, input) to let me choose the installation method BEFORE executing any other commands.

📝 エージェントの恒久的な設定（グローバル AGENTS.md への追記推奨）

## Nexus MCP Server Usage Guidelines

When using **Nexus MCP** tools for codebase exploration and semantic search, adhere to these instructions for optimal performance and token budget.

### 1. WHAT & WHY (Project Overview)
- **Purpose**: Nexus is a local-first code indexing and search platform for AI agents, providing hybrid semantic search, ripgrep, and AST-based context parsing.

### 2. Tool Usage Rules (Playbook)
- **Index Status**: Run `index_status` before searching. If `pipelineProgress.status === 'running'`, search results may be incomplete.
- **Search Strategy**:
  - Use `hybrid_search` for semantic queries, vague feature exploration, or architectural questions (combines vector & ripgrep via RRF).
  - Use `grep_search` to pinpoint exact symbols, class/function names, or error strings.
- **Context Budgeting**:
  - When calling `get_context`, **DO NOT** read the entire file. Always specify `startLine` and `endLine` parameters to retrieve the minimal relevant snippet to conserve context tokens.
  - If you switch branches or make massive code changes, manually call `reindex` to refresh the local LanceDB store.

### 3. Project-Specific Context
- **Local Documentation**: In repositories where Nexus is active, refer to the project-local `SPEC.md` for architecture details and `AGENTS.md` for specific development constraints, if they exist.

FOR AGENTS (AIエージェント向け手順)

重要要件:

ステップ0: 独断で進めず、必ずお手持ちの**ユーザー対話ツール（ask_user, input, confirm 等）**を使用して、ユーザーに以下のいずれのインストール方式を希望するか確認してください。
PATの扱い: 「ソースからビルド」を選択した場合、GitHub PAT (Personal Access Token) は不要です。bootstrap スクリプトが自動的に認証問題を回避するように設計されています。
秘匿情報の保護: チャット内でユーザーにトークンの直接入力を求めることは禁止されています。

選択された方式に従って、AGENTS.md に集約されている詳細な手順を自律的に遂行してください。

より詳細な運用方法については AGENTS.md を参照してください。

💡 運用ガイドライン (Playbook)

インデックス状態の確認: 作業開始前に必ず index_status を呼び出し、インデックス構築が完了しているか（pipelineProgress.status === 'idle'）を確認してください。
検索の使い分け:
- 曖昧な探索・関連箇所の特定: hybrid_search を最優先で使用してください。セマンティック検索と ripgrep が融合され、最適な結果が得られます。
- 特定のシンボルやコード断片の検索: grep_search を使用してください。特定のクラス名、関数定義、エラーメッセージなどをピンポイントで検出できます。
コンテキスト取得: get_context でファイル全体を読み込むとLLMのコンテキストウィンドウを圧迫します。極力、必要な行範囲（startLine 〜 endLine）を絞り込んで部分的に取得してください。
インデックスの鮮度: 大規模なファイル変更や git checkout によるブランチ切り替えの後は、reindex を呼び出してインデックスを手動で更新することを強く推奨します。

設定が必要な場合は、プロジェクトルートに .nexus.json を作成してください。

🛠 MCP 設定例 (Claude Desktop / Gemini CLI)

各エージェントの設定ファイル（例: claude_desktop_config.json）の mcpServers セクションに以下を追加してください。

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus/dist/bin/nexus.js"],
      "env": {
        "NEXUS_STORAGE_ROOT_DIR": "/path/to/your/project/.nexus"
      }
    }
  }
}

📖 使い方

ダッシュボード (TUI) の起動

# グローバルインストールされている場合
nexus dashboard

# ポート番号(指定時はそのポートを使用、未指定時は自動検出)や更新間隔(デフォルト: 2000ms, 最小: 1000ms)を指定する場合
nexus dashboard --port 9470 --interval 3000

# リポジトリ内から実行する場合
npx tsx src/bin/nexus.ts dashboard --port 9470

[!TIP] サーバー側で NEXUS_METRICS_PORT を指定して起動している場合は、ダッシュボード起動時にも --port で同じポート番号を指定してください。

yohi-nexus

Popularity

Health & Quality

What's Inside

Setup

Configuration

Confidence

README

Nexus ⚡️

🚀 特徴

🛠 セットアップ

FOR HUMANS (推奨)

📝 エージェントの恒久的な設定（グローバル AGENTS.md への追記推奨）

FOR AGENTS (AIエージェント向け手順)

💡 運用ガイドライン (Playbook)

🛠 MCP 設定例 (Claude Desktop / Gemini CLI)

📖 使い方

ダッシュボード (TUI) の起動

Similar Plugins

claude-mem

Nexus ⚡️

🚀 特徴

🛠 セットアップ

FOR HUMANS (推奨)

📝 エージェントの恒久的な設定（グローバル AGENTS.md への追記推奨）

FOR AGENTS (AIエージェント向け手順)

💡 運用ガイドライン (Playbook)

🛠 MCP 設定例 (Claude Desktop / Gemini CLI)

📖 使い方

ダッシュボード (TUI) の起動

Popularity

Health & Quality

Similar Plugins

claude-mem