Void Stack

Void Stack

バックエンド、フロントエンド、ワーカー、データベースを含むプロジェクトが10個もあるのに、どれをどう起動するのか思い出せないことはありませんか？ しかも、AI エージェントはプロジェクトを理解するまでに、リポジトリの半分を読んでしまいます。

Void Stack はその両方を解決します。

• 1つのコマンドで開発スタック全体を起動 — バックエンド、フロントエンド、データベース、Docker、WSL に対応します。ポートやコマンドを覚えたり、ターミナルを5つ開いたり、古い README を読んだりする必要はありません。
• MCP 経由で AI エージェントにローカルコンテキストエンジンを提供 — ハイブリッド検索（BM25 + 高精度なベクトル検索 + Tree-sitter のコールグラフ）、プロジェクトマップ、エントリーポイントを備えています。プロジェクトを同じ深さまで理解するために、エージェントが読むテキスト量は、ファイルを手作業で読む場合と比べて約91％削減されます（実測値）。

void add my-app F:\projects\my-app    # Auto-detects services
void start my-app                      # Starts everything

使い方はこれだけです。Void Stack がプロジェクトをスキャンし、使用中のフレームワーク（FastAPI、Vite、Express、Django など）を検出して、適切なコマンドを生成し実行します。Python の仮想環境があれば見つけます。node_modules がなければ、そのことを知らせます。

高パフォーマンス — Rust で構築されています。ランタイムのオーバーヘッドはなく、瞬時に起動し、メモリ使用量も最小限です。

エージェント型ワークフロー — 75個のツールを備えた MCP サーバーにより、Claude Desktop / Claude Code はサービスの管理、コードの検索とマッピング、プロジェクト間の API 契約の確認、セキュリティ監査を自律的に行えます。コードコンテキストだけが必要な場合は、void-stack-mcp --tools context を使うと、コードコンテキスト用の20個のツールを公開でき、セッションあたりのツール定義を64％削減できます（55,147 → 20,025文字）。

クラウドネイティブのロードマップ — 同じ設定から Vercel、DigitalOcean などにデプロイできる機能を近日公開予定です。

スペイン語で読む | void-stack.dev

---

ドッグフーディング：Void Stack による自己分析

Void Stack 自身の分析・監査ツールを使って、コードベースの品質を維持しています。プロジェクト上で void analyze void-stack --compare と void audit void-stack を実行して明らかになったこと、そしてその結果をコードの改善にどう活用したかを紹介します。

セキュリティ監査

void audit void-stack
# Risk Score: 2/100
# 2 low findings (innerHTML usage — already mitigated with DOMPurify)

最初の監査では6件の問題（リスクスコア25/100）が見つかりましたが、そのうち4件は誤検出でした。検出コード内の正規表現パターンやテンプレートが「シークレット」と判定されていたのです。これを受けて、スマートな誤検出フィルタリング（自己参照ファイルの許可リスト、正規表現メタ文字の検出、テンプレート行のフィルタリング）を追加し、誤検出率を83％から0％に下げました。

コード分析

void analyze void-stack --compare
# Pattern: Layered (80% confidence)
# 214 modules, 32,453 LOC, 37 external deps
# Max complexity: 152 (i18n en/es — data tables, not logic)
# Anti-patterns: 26 (4 medium God Class, 13 Fat Controller, 8 Excessive Coupling)

リファクタリングのきっかけとなった指摘事項：

指摘事項	実施した対応
ゴッドクラス：cli/main.rs（1202 LOC、25 fn）	6 つのコマンドモジュールに分割（main は約 250 LOC）
ゴッドクラス：mcp/server.rs（1197 LOC、35 fn）	10 個のツールモジュールに分割（server は約 340 LOC）
ゴッドクラス：manager.rs（30 fn）	4 つのサブモジュールに分割（process、state、logs、url）
ゴッドクラス＋ファットコントローラー：vuln_patterns.rs（789 LOC）	5 つのカテゴリモジュールに分割（injection、xss、network、crypto、config）
ゴッドクラス：db_models.rs（1065 LOC）	DB 形式ごとに 7 つのサブモジュールに分割（python、sequelize、gorm、drift、proto、prisma）
ゴッドクラス：generate_dockerfile.rs（821 LOC）	言語ごとに 6 つのサブモジュールに分割（python、node、rust、go、flutter）
ゴッドクラス：api_routes.rs（747 LOC）	プロトコルごとに 5 つのサブモジュールに分割（python、node、grpc、swagger）
ゴッドクラス：architecture.rs（788 LOC）	4 つのサブモジュールに分割（externals、crates、infra）
ゴッドクラス：classifier.rs（759 LOC、44 fn）	3 つのサブモジュールに分割（logic、signals/data tables、tests）
ファットコントローラー：cli/analysis.rs（580 LOC）	4 つのサブモジュールに分割（analyze、diagram、audit、suggest）
CC=42：analyze_best_practices	テーブル駆動型のリンターレジストリ（CC 約 15）
CC=41：cmd_analyze	11 個のヘルパー関数を抽出（CC 約 10）

技術的負債の追跡

void analyze void-stack --compare --label v0.31.0
# Pattern: Layered (80% confidence)
# Coverage: 83.0% (latest lcov snapshot — core at 90.6%)
# Explicit debt: 34 markers (TODO: 11, TEMP: 10, OPTIMIZE: 6, BUG: 3, XXX: 2, FIXME: 1, HACK: 1)
# 2313 tests passing across the workspace (desktop app not included)

v0.22.0 の新機能：明示的な負債マーカー（TODO/FIXME/HACK/XXX/OPTIMIZE/BUG/TEMP/WORKAROUND）をソースコメントからスキャンし、CLI の出力、Markdown レポート、デスクトップアプリの Debt タブに表示するようになりました。複雑な関数（CC≥10）はカバレッジデータと相互参照され、カバレッジのない重要な関数には、CLI では [!] 警告、Markdown では 🔴 インジケーターが表示されます。

---

ハイブリッドコンテキストエンジン — セマンティック検索＋構造解析

多くの AI ツールでは、セマンティック検索（関連する概念を見つける）か、構造グラフ（呼び出しチェーンを追跡する）のどちらかを選ぶ必要があります。Void Stack は両方を組み合わせます。ベクトル埋め込みは概念的に何が関連しているかを見つけ、Tree-sitter グラフは構造上どこが壊れるかを示します。その結果、単一のアプローチのツールでは実現できない、的確なコンテキストを提供します。

アプローチ	クエリ	結果
セマンティック検索のみ	「auth middleware flow」	概念的に関連するチャンク
構造解析のみ	「validateToken の呼び出し元」	直接の呼び出しチェーン
ハイブリッド（Void Stack）	両方を同時に検索	関連するチャンク＋影響範囲

Void Stack は、BAAI/bge-small-en-v1.5 の埋め込みを使ってコードベースをローカルでインデックス化し、Tree-sitter の呼び出しグラフを構築します。そのため、AI アシスタントはすべてのファイルをスキャンするのではなく、重要な箇所だけを読み取ります。

仕組み

# Index once (runs in background, ~30s for 250 files)
void index my-project

# Get the lay of the land first: packages, entry files, key docs; then every entry point
void map my-project
void entrypoints my-project --kind rest,cli

# Search by concept, not by filename
void search my-project "authentication middleware flow"
# Returns the 5 most relevant hits, compact: path:lines, symbol, the matching lines
# (--detail full for whole chunks; MCP agents expand a hit with get_chunk)

# Incremental re-index driven by git, not timestamps
void index my-project --git-base HEAD~1   # only files changed since last commit
void index my-project --force             # full rebuild

# From Claude Desktop / Claude Code via MCP:
#   build_structural_graph my-project          (Tree-sitter, 14 languages)
#   get_impact_radius      my-project          (blast radius BFS)
#   query_graph            my-project callers  (who calls this function)
#   watch_project          my-project          (auto re-index on save)
#   install_index_hook     my-project          (post-commit re-index)

結果はデフォルトでコンパクトに表示されます。場所、シンボル、一致した行が表示され、同じ接続ですでに送信されたヒットは全体ではなく、↺ マーク付きのコンパクトな形式で返されます（非表示にはなりません。同じ接続を共有するサブエージェントも引き続き確認できます）。インポートのみのブロックはスキップされ、クエリで指定されない限り、テスト、ドキュメント、変更履歴の順位は低くなります。

検索はデフォルトでハイブリッドです。BM25（SQLite FTS5、snake_case の識別子は分割せず保持）とベクトル検索の結果を Reciprocal Rank Fusion で統合するため、埋め込み検索では見つからない場合でも、stop_unix_process_group のような完全一致の識別子を検索できます。モード：hybrid | vector | lexical。

0.36 と 0.35 の比較（Windows、登録済みプロジェクト70件、MCP サーバー経由で同じクエリを実行）

指標	0.35	0.36	変化
プロジェクトの理解（morrocoy、430ファイルの Flutter アプリ）：同じ5つの質問	10,586文字	10,556文字	手作業で必要な13ファイルを読んだ場合の114,236文字と比べて −91 %
get_api_contracts iunci（Flutter）	410,176文字	33,222文字	−92 %
get_api_contracts iunci-backend（Go）	234,464文字	30,527文字	−87 %
list_entrypoints iunci	23,139文字、実際のルート41件	4,701文字、実際のルート97件	−80 %（ベンダー提供の .proto コピー1,475件を除外）
check_contracts（3プロジェクトの平均）	20.5秒	0.89秒	23倍高速
セッションあたりのツール定義数（--tools context を指定した0.36）	55,147文字	20,025文字	−64 %
build_structural_graph morrocoy	2.9秒	0.8秒	高速化

この5つの質問に project_map と list_entrypoints を加えると、合計は18,055文字（手作業の場合と比べて−84 %）となり、アプリのMCP ツール70件が一覧表示されます。0.33では、同じ5つの質問で約49,000文字が返されました（以前のマシンでの推定値）。check_contracts が高速化したのは、サイズと変更時刻が変わっていないファイルを再読み込みせずにスキップし、プロデューサーを並列でスキャンするためです。

GPU でのインデックス作成（0.36の新機能。Windows、DirectML、RTX 4070 Ti SUPER）：

プロジェクト	チャンク数	CPU	GPU	高速化
iunci	12,206	740–1,003秒	73–75秒	約10～13倍
void-stack	6,467	623秒	40秒	約16倍
morrocoy	1,371	101–281秒	22秒（新しいバイナリでの初回実行時は38秒。DirectMLがシェーダーをコンパイルするため）	—

埋め込みはCPUの場合と同一で（12,206チャンクすべてでコサイン類似度1.000000）、検索結果も同じです。

0.35 と 0.34 の比較（実際のプロジェクト11件、同じマシン、MCP サーバー経由で同じクエリを実行）

セッション	0.34のトークン数	0.35のトークン数	削減率
「すべての機能を一覧表示」（マップ＋エントリポイント＋検索8件）、プロジェクト8件	177,136	48,586	3.6倍
git 履歴から抽出した検索140件（プロジェクト7件）	332,233	60,494	5.5倍
同じ4つの質問を1つのセッションで2回実行	37,992	4,358	8.7倍
プロジェクト横断（3トピック × 3プロジェクト＋クロス GraphRAG＋コントラクト）	109,391	7,833	14倍

検索品質は同等以上（git 履歴に関する140件のクエリで hit@5 は0.679 → 0.686、recall@5 は0.514 → 0.538）で、上位5件に含まれるノイズの多いヒット（テスト、インポートのみのブロック、変更履歴）は180件から54件に減少し、検索レイテンシーは変わりません（p50 約10ミリ秒）。また、検索のみのインベントリで検出できたのは8パッケージだったのに対し、project_map は21クレートのワークスペースに含まれる21パッケージすべてを検出しました。インデックス作成時間とピーク RAM は0.34と同じです。void bench <project> --task queries.txt でクエリごとの数値を再現できます。

ベンチマーク（void-stack 自体で測定）

操作	インデックスなし	void-stack 使用時	削減率
semantic_search（平均）	ファイルあたり約170行	結果あたり約4行	97.5 %
モジュールの理解	ファイルを5～10個読み込み	検索クエリ1回	約10倍
変更の影響範囲	手作業で数時間	get_impact_radius	即時

97.5 %という数値は、void stats --days 90 が報告した、135回の semantic_search 操作における値です。LLM のコンテキストに入らなかったソースコードは23,868行でした。

フットプリント（v0.33、Windows、void-stack をゼロからインデックス化、約3,000チャンク）：約110秒、ピーク時の RAM 使用量は約650 MBです。v0.31の193秒、4.2 GBから改善されています。ベクトル検索は厳密検索（int8 ベクトル、再現率1.0）で、インデックスのメモリ使用量は7.3 MBです。詳細はCHANGELOGをご覧ください。

GPU によるインデックス化（0.36）：Windows では void index が DirectML を介して GPU 上で埋め込みを生成します（NVIDIA、AMD、Intel の DirectX 12 対応 GPU で利用可能）。追加インストールは不要で、GPU がない場合は CPU にフォールバックします。検索クエリの埋め込み生成には引き続き CPU を使用します（数ミリ秒）。VOID_STACK_EMBED_DEVICE=cpu を指定すると CPU を強制的に使用します。GPU バッチのデフォルトは32です（VOID_STACK_EMBED_BATCH で変更できます。同じ速度で、バッチ32ではビデオメモリを2.5 GB、128では8.8 GB使用します）。現時点では macOS と Linux は CPU でインデックス化します。インデックス化の後、CLI に embeddings: GPU (DirectML) または embeddings: CPU と表示されます。

対応言語

• セマンティックインデックス（埋め込み）：CODE_EXTENSIONS に含まれるすべてのソース拡張子 — Rust、Python、JS/TS、Go、Dart、Java、PHP、C/C++、C#、Ruby、Swift、Kotlin、Lua、Zig、Elixir、Verse、GDScript、MQL4/MQL5、Vue、Svelte、Astro、および md/proto/sql/dockerfile。
• 構造グラフ（Tree-sitter）：Rust、Python、JavaScript、TypeScript（+ TSX）、Go、Dart、Java、PHP、C、C++、Elixir、C#、Swift、GDScript、MQL4/MQL5（C++ 文法）。
• 依存関係グラフ（インポート）：Python、JS/TS、Go、Dart、Rust、Verse、C#、Swift、GDScript、C/C++、MQL4/MQL5 — C# は using を、その名前空間を宣言するファイルに関連付けます。Swift は import を SwiftPM ターゲットに関連付けます。GDScript は res:// パスと class_name を解決します。C/C++ は Unreal のモジュールインクルードパスと同様に #include "…" を解決します。MQL は #include <…> をターミナルの Include/ フォルダーに対して解決します。
• ゲームエンジン：Unity（C#）、Unreal Engine（C++ / UEFN Verse）、Godot（GDScript / C#）のプロジェクトは、各エンジンのマーカーから検出されます。キャッシュ／ビルドフォルダー（Library/、Intermediate/、.godot/ など）はすべてのスキャナーでスキップされ、Space パネルから削除できます。
• MetaTrader：MQL4/MQL5 プロジェクト（.mq4/.mq5/.mqh、または MQL4/MQL5 データフォルダー）が検出されます。MetaEditor の UTF-16 ソースは自動的に読み込まれ、ターミナルのイベントハンドラー（OnInit、OnTick、OnCalculate など）はデッドコードとして報告されません。また、コンパイル済みの .ex4/.ex5 ファイルは除外されます。

構造解析はcode-review-graph（MIT）に着想を得ています — AST ノードのマッピングと BFS クエリロジックを Rust でネイティブに再実装しています。

---

インターフェース

Void Stack には4つのインターフェースがあります。お好みのものをご利用ください。

インターフェース	説明
CLI（void）	ターミナルから素早くコマンドを実行
TUI（void-stack-tui）	対話型のターミナルダッシュボード：サービス、分析、セキュリティ監査、負債、容量
デスクトップ（void-stack-desktop）	GUI を備えたデスクトップアプリ（Tauri + React）— Windows（.msi）、macOS（.dmg）、Linux（.deb）
MCP サーバー（void-stack-mcp）	Claude Desktop / Claude Code との連携

エンドツーエンドの例：FastAPI + React を30秒で

FastAPI バックエンドと React フロントエンドを持つプロジェクトがあるとします。

my-app/
├── backend/       # FastAPI with venv
│   ├── main.py    # from fastapi import FastAPI
│   └── .venv/
├── frontend/      # React with Vite
│   ├── package.json
│   └── src/
└── .env

# 1. Register the project (scans and detects services)
void add my-app F:\projects\my-app

# Void Stack detects:
#   ✓ backend  → uvicorn main:app --host 0.0.0.0 --port 8000
#   ✓ frontend → npm run dev
#   ✓ .venv    → auto-resolves python to virtualenv

# 2. Check dependencies
void check my-app
#   ✅ Python 3.11 (venv detected)
#   ✅ Node 20.x (node_modules up to date)
#   ✅ .env complete vs .env.example

# 3. Start everything
void start my-app
#   [backend]  → http://localhost:8000
#   [frontend] → http://localhost:5173

# 4. Or open the interactive dashboard
void-tui my-app

インストール

バイナリ（推奨）

Releases ページからビルド済みバイナリをダウンロードしてください。Rust は不要です。

プラットフォーム	ファイル
Windows	.msi / .exe (NSIS)
macOS	.dmg
Linux	.deb / .AppImage

Claude Desktop Extension — 各リリースには、プラットフォームごとの .mcpb ファイルも含まれています。.mcpb を Claude Desktop にドロップするだけで、設定不要で MCP サーバーをインストールできます。

バイナリにはベクトル検索が含まれます — Releases から入手できるビルド済みバイナリには、BAAI/bge-small-en-v1.5 を利用したセマンティックコード検索が含まれています（ローカルで動作し、API キーは不要です）。埋め込みモデル（約 130MB）は、初めて void index を実行したときに自動でダウンロードされます。ベクトル検索なしでビルドするには、cargo build --release -p void-stack-cli を実行してください。

macOS に関する注意： 「開発元を検証できないため開けません」 と表示された場合は、次を実行してください。

xattr -cr /Applications/Void\ Stack.app

ソースから（Cargo）

# Core CLI (the main tool)
cargo install --git https://github.com/mague/void-stack void-stack-cli

# TUI Dashboard
cargo install --git https://github.com/mague/void-stack void-stack-tui

# MCP Server (for AI integration with Claude Desktop / Claude Code)
cargo install --git https://github.com/mague/void-stack void-stack-mcp

# gRPC Daemon (optional, for persistent management)
cargo install --git https://github.com/mague/void-stack void-stack-daemon

前提条件： Rust + Protobuf コンパイラ（Windows では winget install Google.Protobuf）

ソースからビルドする

git clone https://github.com/mague/void-stack.git
cd void-stack

# With vector search (recommended):
cargo build --release --features vector

# Minimal build (no ONNX dependency):
cargo build --release

# Binaries in target/release/
#   void              — CLI
#   void-stack-tui    — Terminal dashboard
#   void-stack-daemon — gRPC daemon
#   void-stack-mcp    — MCP server for AI (always includes vector search)

デスクトップアプリ（Tauri）

cd crates/void-stack-desktop
cargo tauri build
# Generates installer in target/release/bundle/

差分中心のワークフロー：テストの選定と LLM 向けレビュー

大規模なコードベースでの実装 → テスト → レビューのサイクルを、2 つのツールで短縮できます。

suggest_tests_for_diff — 差分をカバーするテストだけを実行します。逆カバレッジマップ（テスト → 構造グラフ上の BFS 呼び出し先。SQLite にキャッシュ）を使って、変更されたシンボルをカバーするテストに対応付け、呼び出し距離順に並べます。また、明示的な 未カバー リストと、そのまま貼り付けて使えるコマンドも出力します。

$ void suggest-tests void-stack
## Suggested tests (3 for 7 changed symbols)
- `test_stop_one_waits_for_child_exit` — crates/void-stack-core/src/manager/process.rs:441 (hop 1)
## Uncovered (1)
- ⚠️ `render_html` — crates/void-stack-core/src/diagram/graph_html.rs:289 has NO covering tests
## Run
cargo test -p void-stack-core test_stop_one_waits_for_child_exit

review_diff — 現在の差分をレビューするための簡潔なペイロード（≤4k トークン）です。LLM レビュアーへの入力として設計されており、概要、変更行のみを対象とした監査結果（抑制設定を考慮）、ホップ数ラベル付きの影響範囲、テストカバレッジ、および最も重要なシンボルの 1 ホップ分の呼び出しコンテキストを含みます。

$ void review void-stack --git-base main
# Review — void-stack (vs `main`)
## Summary
- 12 files changed, +840 / -95 lines
## Findings on changed lines (1) | Suppressed: 2
- [medium] Use of .unwrap() in production code — `crates/.../db.rs:44` → Replace with '?'
## Blast radius (depth 2)
- `crates/void-stack-mcp/src/tools/search.rs`: semantic_search (hop 1) ...

ワークフロー：編集の各バッチ後に、全テストスイートではなく提案されたテストを実行します。各コミットの前に review_diff を実行し、Critical／High の指摘と未カバーリストに対応します。skills/skill-void-stack スキルには、Claude Code セッション向けのこれらのルールが記載されています。

セキュリティと信頼モデル

Void Stack はサービスランチャーです。void-stack.toml（および登録済みサービス）内の command 文字列は、プラットフォームのシェル（Unix では sh -c、Windows では cmd /c）を通じて、ユーザーの権限でそのまま実行されます。これは意図した動作ですが、プロジェクト設定は信頼できる入力でなければなりません。

• 内容を確認していないリポジトリからサービスを起動しないでください。悪意のある void-stack.toml は任意のコードを実行します。
• デーモンは、新たに読み込まれたプロジェクトのサービスコマンドを実行する前に、一度だけ確認を求めます。承認情報はユーザーの設定ディレクトリ（Linux では ~/.config/void-stack/trusted-projects.json、macOS では ~/Library/Application Support/void-stack/）に保存され、プロジェクト内には保存されません。また、コマンド一式の正確なハッシュに紐付けられるため、コマンドが変更されると再度確認が求められます。対話なしで承認するには、void-daemon start --yes を使用してください（CI、スクリプト向け）。
• 承認する前に、一覧表示されたコマンドを確認してください。再度確認を求められるようにするには、trusted-projects.json からプロジェクトの項目を削除してください。

MCP クライアントに登録する

void setup            # detects Claude Desktop/Code, Cursor, Windsurf, Cline, VS Code
void setup --dry-run  # see what would change first

分析対象からファイルを除外する

プロジェクトのルートに .voidignore を作成して、void analyze の対象からパスを除外します。

# Generated code
internal/pb/
vendor/
**/*.pb.go
**/*.pb.gw.go

# Mocks
**/mocks/
**/*_mock.go

.gitignore と同じ構文（簡易版）です。プレフィックスパス、**/ グロブサフィックス、ディレクトリ名に対応しています。

機能

• マルチサービス — すべてのサービスをまとめて、または個別に起動・停止できます
• クロスプラットフォーム — Windows（cmd）、macOS、WSL（bash）、Docker コンテナ、SSH（今後対応予定）
• 自動検出 — ディレクトリをスキャンし、Python、Node、Rust、Go、Flutter、Docker、Elixir、Unreal Engine / UEFN（.uproject、.uplugin、.verse）、Unity（ProjectSettings/ProjectVersion.txt）、Godot（project.godot）、Swift（Package.swift、.xcodeproj）を識別します
• スマートコマンド — FastAPI、Flask、Django、Vite、Next.js、Express、Air（Go のホットリロード）を検出し、適切なコマンドを生成します
• 起動前フック — 起動前に、サービスごとに仮想環境を自動作成し、依存関係（pip install、npm install、go mod download）をインストールします。設定不要で、すぐに使用できます
• 依存関係チェック — Python、Node、CUDA、Ollama、Docker、Rust、.env を検証します
• ライブログ — すべてのサービスの標準出力／標準エラーを表示し、URL を自動検出します
• カンバンボード — Git でバージョン管理される BOARD.md（CLI、MCP、デスクトップ）：タスクごとの履歴と作業タイムラインは、ボードの Git ログを一括で読み取って再構成します（コミットごとにプロセスを起動して数秒かかっていた Windows でも高速です）。WSL 上のプロジェクト（\\wsl.localhost\… のルート）にも対応し、Git の処理は wsl.exe 経由で実行されます
• 図表 — 統合スキャナーを使用し、プロジェクト構造から Mermaid と Draw.io を生成します（アーキテクチャ、Swagger/OpenAPI の情報を補完した API ルート、内部／外部 API の分離、gRPC/Protobuf サービス、外部キーの近接性に基づくレイアウトの DB モデル — Prisma、Sequelize、GORM、Django、SQLAlchemy、Drift）
• コード分析 — 依存関係グラフ、アンチパターン、循環的複雑度、カバレッジ
• ベストプラクティス — ネイティブリンター（react-doctor、ruff、clippy、golangci-lint、dart analyze）と統合スコアリング
• 技術的負債 — メトリクスのスナップショットとトレンド比較
• AI 連携 — Claude Desktop / Claude Code 向けの 75 個のツールを備えた MCP サーバー。Ollama（ローカル LLM）を使った AI によるリファクタリング提案に対応し、利用できない場合は適切にフォールバックします。セマンティックインデックスが存在する場合は、複雑度の高い箇所や巨大なクラスから取得した実際のコードスニペットをプロンプトに追加します
• セマンティックコード検索 — BAAI/bge-small-en-v1.5 の埋め込みを使い、任意のプロジェクトをローカルでインデックス化できます（100％オフライン、初回のみ約 130 MB のダウンロードが必要です）。void search と semantic_search MCP ツールは、関連するチャンクのみを返します。void-stack 自身のコードベースに対する 135 件のクエリでの測定では、ファイルを直接読む場合と比べてトークンを 97.5％削減しました。
• 構造的コールグラフ — Tree-sitter を利用した関数レベルの分析に対応する言語は、Rust、Python、JS、TS、Go、Dart、Java、PHP、C、C++（Unreal Engine を含む）、Elixir、C#（Unity / Godot .NET）、Swift、GDScript（Godot）です。Verse（UEFN）はインポートアナライザー、セマンティックインデックス、負債スキャナーで対応しています（現時点で Tree-sitter の文法はありません）。データは .void-stack/structural.db（WSL 上のプロジェクトでは %LOCALAPPDATA%\void-stack\structural\<project>\）に保存されます。影響範囲の BFS（get_impact_radius）を使えば、コードに手を加える前に「このファイルを変更すると、何が壊れるか？」を確認できます。
• 増分インデックス作成 — Git 差分と SHA-256 ハッシュを利用します。--git-base HEAD~1 を指定すると、前回のコミットから実際に変更されたファイルのみを再インデックス化します。watch_project（MCP）は保存時に 500 ms のデバウンスで自動的に再インデックス化します。install_index_hook（MCP）はコミット後フックを設定し、コミットのたびにインデックスを最新の状態に保ちます。
• ディスク容量スキャナー — プロジェクトの依存関係（node_modules、venv、target）とグローバルキャッシュ（npm、pip、Cargo、Ollama、HuggingFace、LM Studio）をスキャンしてクリーンアップします
• デスクトップ GUI — サイバーパンクなミッションコントロールをイメージした Tauri アプリです。視覚的な階層構造（KPI カード、グロー効果、重大度のグラデーション）を備え、サービス、ログ、依存関係、図表、分析、ドキュメント、セキュリティ、負債、ディスク容量を表示します
• デーモン — 管理状態を保持するための、オプションの gRPC デーモン
• セキュリティ監査 — 依存関係の脆弱性、ハードコードされたシークレット、安全でない設定、コードの脆弱性パターン（SQL インジェクション、コマンドインジェクション、パストラバーサル、XSS、SSRF など）を検出し、スマートな誤検知フィルタリングを行います（自己参照型の検出パターン、正規表現の定義、テンプレート、JSX 要素、リファクタリングを含む Git 履歴のコミット、波括弧の深さ追跡によるテストモジュールを除外します）
• Docker Runner — target = "docker" を指定したサービスは Docker コンテナ内で実行されます。モードは 4 種類です。生の Docker コマンド、イメージ参照（postgres:16 → docker run を自動実行）、Compose の自動検出、Dockerfile のビルドです。Compose は、すべてのコンテナをまとめて起動する単一の docker compose up サービスとしてインポートされます。docker: プレフィックスで Docker サービスとローカルサービスを区別できます。ポート、ボリューム、追加引数はサービスごとに設定できます。プロセス終了ウォッチャーが失敗を検出し、ステータスを自動更新します
• Docker インテリジェンス — Dockerfile と docker-compose.yml を解析し、フレームワークごとに Dockerfile（Python、Node、Rust、Go、Flutter）を自動生成します。自動検出したインフラ（PostgreSQL、Redis、MongoDB など）を使って docker-compose.yml も生成します
• インフラストラクチャインテリジェンス — Terraform のリソース（AWS RDS、ElastiCache、S3、Lambda、SQS、GCP Cloud SQL、Azure PostgreSQL）、Kubernetes マニフェスト（Deployments、Services、Ingress、StatefulSets）、依存関係を含む Helm チャートを検出し、すべてアーキテクチャ図に統合します
• セキュリティ — .env の値は読み取らず、機密ファイルを一元的に保護します

CLI

コマンド	説明
void add <n> <path> [--tag T]	プロジェクトを登録します（サービスを自動検出します）
void tag <project> [TAGS…] [--remove T] [--clear]	プロジェクトを自分のもの（own / propio）または他人のもの（third-party / tercero）としてマークするか、任意のラベルを追加します
void add-service <project> <n> <cmd> -d <dir>	サービスを手動で追加します
void edit-service <project> <svc> [-c CMD] [-d DIR] [-t TARGET] [--rename N] [--enable|--disable]	サービスを編集します（例：自動検出された動作しないコマンドを修正します）
void remove-service <project> <svc>	プロジェクトからサービスを削除します
void remove <n>	プロジェクトの登録を解除します
void list [--tag T]	プロジェクトとサービスを一覧表示します（タグが付いたもののみ）
void scan <path>	登録せずに検出結果をプレビューします
void start <project> [-s service]	すべてのサービス、または1つのサービスを起動します
void stop <project> [-s service]	すべてのサービス、または1つのサービスを停止します
void status <project>	リアルタイムのステータスを表示します：PID、URL、稼働時間
void check <project>	依存関係を確認します
void diagram <project> [-f mermaid|drawio] [--print-content]	図を生成します
void audit <project> [-o file]	セキュリティ監査を実行します
void analyze <project> [--compare] [--cross-project] [--best-practices]	コードを分析します
void docker <project> [--generate-dockerfile] [--generate-compose] [--save]	Docker 関連の分析を行います
void suggest <project> [--model <m>] [--service <s>] [--raw]	AI によるリファクタリングの提案を表示します（Ollama）
void read-file <project> <path>	プロジェクト内の任意のファイルを読み取ります（.env、認証情報はブロックされます）
void logs <project> <service> [-n lines] [--compact] [--raw]	フィルタリングしたサービスログを表示します
void index <project> [--force] [--generate-voidignore] [--git-base <ref>]	セマンティック検索用にコードベースをインデックス化します（--git-base HEAD~1 は git diff を使用します）
void search <project> "<query>" [-t top_k] [--detail compact|full|auto]	セマンティックコード検索を行います（デフォルトでは、場所、シンボル、一致した行をコンパクトに表示します）
void map <project> [--depth N]	プロジェクトマップを表示します：パッケージ、エントリーファイル、ディレクトリごとのコード、主要なドキュメント
void entrypoints <project> [--kind rest,grpc,mcp,cli,routes,jobs]	すべてのエントリーポイントを表示します：HTTP ルート、RPC、MCP ツール、CLI コマンド、UI ルート、ジョブ
void contracts check <project>	利用している API ルート／RPC を、それらを提供する登録済みプロジェクトと照合します（差異がある場合は終了コードがゼロ以外になります）
void bench <project> --task <file> [--json]	クエリごとのトークン数を比較します：コンパクトな出力、すべてのチャンク、またはファイル全体の読み取り
void stats [--project <p>] [--days <d>] [--json]	トークン削減の統計を表示します
void claudeignore <project> [--dry-run] [--force]	技術スタックに最適化された .claudeignore を生成します

フラグ： --wsl（WSL パス）、--daemon（デーモンに接続）、--compare（スナップショットを比較）、--cross-project（プロジェクト間の依存関係）、--label <tag>（スナップショットにタグを付与）

MCP 専用ツール（Claude Desktop / Claude Code / OpenCode）

これらは CLI コマンドではなく、void-stack-mcp によって公開されます。

ツール	説明
get_chunk	コンパクトな検索結果を展開します：ファイルの line_start..=line_end 行
watch_project / unwatch_project	ファイル変更時に自動で再インデックス化します（約 500 ms のデバウンス）
install_index_hook	変更されたファイルを再インデックス化する post-commit フックをインストールします
build_structural_graph	14 言語を対象とした Tree-sitter 呼び出しグラフ — Rust、Python、JS、TS、Go、Dart、Java、PHP、C、C++、Elixir、C#、Swift、GDScript + MQL4/MQL5（--features structural）
get_impact_radius	影響範囲を BFS で調査します — ファイルの変更によって影響を受ける対象
query_graph	呼び出し元／呼び出し先／テスト／構造グラフに対するあいまい検索
full_analysis	監査 + アーキテクチャ + セマンティックな問題箇所を 1 つのレポートにまとめます（quick/standard/deep）
manage_suppressions	ファイルを手動で編集せずに、監査抑制ルールを一覧表示／追加／削除します
setup_project	ワンクリックでオンボーディングします：登録 + 除外設定の生成 + インデックス化 + 監査 + 分析

構造分析は code-review-graph（MIT）に着想を得ています。

TUI ダッシュボード

void-tui                # All projects
void-tui my-project     # Specific project
void-tui --daemon       # Via daemon

キー	操作
a	すべてのサービスを開始
s	選択したサービスを開始
k	選択したサービスを停止
K	すべて停止
1-5	タブを切り替え（Services/Analysis/Security/Debt/Space）
R	現在のタブでアクションを実行（analyze、audit、scan）
j/↓	下へ移動
l	ログパネルを切り替え
Tab	パネルを切り替え
r	ステータスを更新
L	言語を切り替え（ES/EN）
?	ヘルプ
q	終了（サービスを停止）

**i18n：**スペイン語（デフォルト）と英語に対応しています。L を押すと切り替わります。

**タブ：**Services（管理／監視）、Analysis（アーキテクチャパターン、レイヤー、アンチパターン、複雑度 + カバレッジの相互参照）、Security（リスクスコア、脆弱性の検出結果）、Debt（TODO/FIXME/HACK マーカー）、Space（プロジェクト + 全体のディスク使用量）

デスクトップ（Tauri）

4 ゾーン構成のシェル（トップバー＋レール）、⌘K コマンドパレット、プロジェクトインテリジェンスのパルスラインを備えたデスクトップアプリです。パネルは 実行（サービス、ログ、Docker）、インテリジェンス（検索、レビュー、テスト、デッドコード、分析、セキュリティ、負債）、マップ（グラフ、図、統計）、プロジェクト（依存関係、ドキュメント、ディスク容量）に分類されています。

• トップバー：インデックスを維持したままインラインで名前変更・移動できるプロジェクトピッカーとクイック追加、⌘K コマンドパレット（サービス＋アクション＋セマンティック検索へのフォールバック）、インデックス／グラフの鮮度を示すバイタル（クリックするとグラフを再構築）、言語切り替え（ES/EN）
• パルスライン：レビューの検出結果、提案されたテスト／未カバーのテスト、デッドコード数、監査リスクを1行で示すプロジェクトインテリジェンス。並列取得され、プロジェクトごとにキャッシュされます
• サービス：ステータスドット、言語バッジ、ポートリンク（ブラウザーで開きます）、稼働時間、直近のログ行、開始／停止と削除を備えたカードグリッド。「サービスを追加」するゴーストカード
• ログ：構造化ビューアー（レベルフィルター、検索、追従モード、折り返し／生データの切り替え、パスが検出されたエラー行の「影響」）と、サービスグリッドの下に折りたたみ可能なドロワー
• 検索：セマンティック検索、GraphRAG（セマンティック検索＋構造的なコールグラフ）、UI からのプロジェクト横断 GraphRAG。検索結果をエディターの該当行で開きます
• グラフ：アプリ内のインタラクティブな依存関係グラフビューアー（Cytoscape）。重要度に応じたノードサイズ、近傍のハイライト、レイアウト切り替え、レイヤー／コミュニティ別の色分けに対応。ファイルをクリックすると VS Code／Cursor／Windsurf で開きます
• 図：アーキテクチャ、API ルート、DB モデル向けに Mermaid とネイティブ Draw.io XML を描画します（DOMPurify を使用したカスタム SVG レンダラー）
• 分析／セキュリティ／負債：アーキテクチャパターン、アンチパターン、複雑度、カバレッジ、リスクスコア、脆弱性／シークレットの検出結果、傾向比較付きのメトリックスナップショット
• ドキュメント／ディスク容量／Docker：Markdown ドキュメント、キャッシュのスキャンとクリーンアップ、Docker アーティファクトの解析／生成、Terraform／Kubernetes／Helm の検出
• UX：Geist + JetBrains Mono のタイポグラフィ、フォーカス可視リング、動きを抑える設定への対応、学習用ツールチップ、コピーボタン

MCP サーバー（AI 連携）

Claude Desktop、Claude Code、OpenCode からプロジェクトを直接管理できます。

Windows — %APPDATA%\Claude\claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp.exe"
    }
  }
}

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "void-stack": {
      "command": "/Users/YOUR_USERNAME/.cargo/bin/void-stack-mcp"
    }
  }
}

Linux — ~/.config/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp"
    }
  }
}

OpenCode（無料モデル — API キー不要）— ~/.config/opencode/opencode.json に追加します：

{
  "mcp": {
    "void-stack": {
      "type": "local",
      "command": ["void-stack-mcp"],
      "enabled": true
    }
  }
}

macOS ではフルパスを使用してください：["~/.cargo/bin/void-stack-mcp"]

OpenCode の利点： 無料モデル（MiniMax、Qwen、DeepSeek）で動作します。API コストなしで、void-stack MCP を完全に連携できます。

macOS に関する注意： Claude Desktop と OpenCode は、~/.cargo/bin を含まない最小限の PATH で起動します。バイナリへのフルパスを使用してください。ターミナルで which void-stack-mcp を実行すると確認できます。また、隔離フラグを削除してください。削除しないと macOS がバイナリを警告なしでブロックします：

xattr -d com.apple.quarantine ~/.cargo/bin/void-stack-mcp

リモートクライアント：ストリーミング可能な HTTP（--http）

上記の設定はすべて、サーバーを stdio 経由で起動します。つまり、クライアントごとに同じマシン上で 1 つのプロセスを実行します。代わりに --http を使うと、同じ ツールを MCP ストリーミング可能な HTTP 経由で提供できます。これにより、別のマシン上（または WSL 内）のクライアントが 1 つのサーバーと 1 つのプロジェクトレジストリを共有できます。

void-stack-mcp --http 127.0.0.1:7400   # localhost only
void-stack-mcp --http 7400             # same thing, bare port = loopback
void-stack-mcp --http 0.0.0.0:7400     # reachable from your tailnet/LAN

HTTP に対応する任意の MCP クライアントから登録できます。/ と /mcp のどちらも使用できます。

claude mcp add --transport http void-stack http://localhost:7400

一般的な使い方は、Windows 上でサーバーを実行し、WSL（networkingMode=mirrored の場合、localhost を介して接続できます）または Tailscale 経由で別のマシンから利用する方法です。ツールは実行元ホストのレジストリを読み取るため、すべてのクライアントに同じプロジェクトが表示されます。

認証はありません。 HTTP トランスポートは設計上、認証機能を備えていません。ポートに到達できるユーザーは、プロジェクトにフルアクセスできます。ループバックまたはテイルネット上でのみ使用してください。バインドアドレスがループバックでも Tailscale の範囲（100.64.0.0/10、fd7a:115c:a1e0::/48）でもない場合、サーバーは起動時に警告をログに記録します。オープンインターネットには公開せず、Tailscale（または認証機能を備えたリバースプロキシ）を前段に配置してください。

1 つのプロセスが提供できるのは stdio または HTTP のいずれかであり、両方ではありません。同時に両方を使用するには、2 つ目のプロセスを実行してください。

ツールとトークンを減らす（--tools）

各クライアントは、すべてのツールの定義をコンテキスト内で受け取ります。75 個すべてで、1 セッションあたり 55,147 文字になります。プロファイル、ツール名をカンマ区切りにしたリスト、またはその両方を指定して、クライアントに必要なものだけを公開できます。--tools context を指定すると、1 セッションあたりのツール定義を 64 % 削減できます（55,147 → 20,025 文字）。

void-stack-mcp --tools context            # 20 code-context tools, 20,025 characters
void-stack-mcp --tools devops,get_chunk   # services + one extra tool
VOID_STACK_MCP_TOOLS=review void-stack-mcp

プロファイル：context（マップ、エントリーポイント、検索、グラフ、コントラクト、ドキュメント）、devops（プロジェクト、サービス、ログ、依存関係、Docker）、review（監査、分析、負債、差分レビュー、ボード）。デフォルトと full は、すべてのツールを含みます。

クライアント設定では、プロファイルを args に指定します。

{
  "mcpServers": {
    "void-stack": {
      "command": "void-stack-mcp",
      "args": ["--tools", "context"]
    }
  }
}

利用可能なツール（75 個）： list_projects、project_status、start_project、stop_project、start_service、stop_service、get_logs、add_project、read_project_docs、read_all_docs、read_project_file、list_project_files、generate_diagram、check_dependencies、analyze_project、audit_project、remove_project、update_project、scan_directory、add_service、update_service、remove_service、save_debt_snapshot、list_debt_snapshots、compare_debt、analyze_cross_project、scan_project_space、scan_global_space、docker_analyze、docker_generate、suggest_refactoring、generate_claudeignore、get_token_stats、index_project_codebase、semantic_search、get_chunk、project_map、list_entrypoints、get_index_stats、watch_project、unwatch_project、install_index_hook、build_structural_graph、get_impact_radius、query_graph、generate_voidignore、cluster_project_index、get_cluster_stats、get_communities、graph_rag_search、find_dead_code、review_diff、check_env、check_contracts、suggest_commit_message、session_handoff、daily_briefing、doctor、session_context、board_list、board_add_task、board_move_task、sync_todos、board_archive_done、board_history、board_timeline、commit_detail、board_link_task、suggest_tests_for_diff、get_api_contracts、graph_rag_search_cross、generate_graph_html、full_analysis、manage_suppressions、setup_project

依存関係の検出

検出器	チェック項目
Python	バイナリ、バージョン、venv、pip check
Node	バイナリ、node_modules の鮮度
CUDA	nvidia-smi、ドライバー、GPU、VRAM、PyTorch
Ollama	バイナリ、API のヘルス、ダウンロード済みモデル
Docker	バイナリ、デーモンの状態、compose
Rust	rustc と cargo のバージョン
Go	go version、go.mod の有無
Flutter	flutter --version、dart --version、pubspec.yaml
.env	.env と .env.example を比較

コード分析

void analyze my-app -o analysis.md
void analyze my-app --compare --label v2.0
void analyze my-app --cross-project
void analyze my-app --best-practices
void analyze my-app --bp-only         # Only linters, skip architecture

• パターン — MVC、レイヤード、クリーン／ヘキサゴナルを信頼度付きで分析
• アンチパターン — ゴッドクラス、循環依存、肥大化したコントローラー、過剰な結合
• 循環的複雑度 — 関数単位で分析（Python、JS/TS、Go、Dart、Rust）
• カバレッジ — LCOV、Cobertura、Istanbul、Go カバープロファイル
• グラフ — モジュール間の関係を示す Mermaid ダイアグラム
• 傾向 — 比較機能付きの過去のスナップショット

ダイアグラム

void diagram my-app                 # Draw.io (default)
void diagram my-app -f mermaid      # Mermaid markdown

検出対象：サービスアーキテクチャ、外部サービス（ソースコードと .env から URL を抽出）、サービス間の内部呼び出し（ポートによる localhost の相互参照）、Swagger/OpenAPI の情報を補完した API ルート（FastAPI、Flask、Express、gRPC/Protobuf）、内部 API と公開 API の分離、DB モデル（SQLAlchemy、Django、Prisma、Sequelize、GORM、Drift、Protobuf メッセージ）、Rust クレート間の関係。

アーキテクチャ

void-stack/
├── crates/
│   ├── void-stack-core/       # Core library: models, config, runners, detectors, analyzers
│   ├── void-stack-proto/      # Protobuf definitions + gRPC client
│   ├── void-stack-daemon/     # Daemon with gRPC server (tonic)
│   ├── void-stack-tui/        # Terminal dashboard (ratatui)
│   ├── void-stack-mcp/        # MCP server for AI assistants
│   ├── void-stack-desktop/    # Tauri v2 app (React + TypeScript)
│   └── void-stack-cli/        # CLI interface (clap)
├── example-void-stack.toml
└── CHANGELOG.md

設定

void-stack.toml（プロジェクトごと）

name = "my-fullstack-app"
description = "Full stack app"
project_type = "node"

[hooks]
install_deps = true

[[services]]
name = "backend-api"
command = "npm run dev"
target = "wsl"
working_dir = "./backend"

[[services]]
name = "web-frontend"
command = "npm run dev"
target = "windows"
working_dir = "./frontend"

[[services]]
name = "database"
command = "docker compose up postgres redis"
target = "docker"

[[services]]
name = "cache"
command = "redis:7-alpine"
target = "docker"
[services.docker]
ports = ["6379:6379"]

グローバル設定

すべてのプロジェクトは、プラットフォーム固有の場所に保存されます。

• Windows: %LOCALAPPDATA%\void-stack\config.toml
• macOS: ~/Library/Application Support/void-stack/config.toml
• Linux: ~/.config/void-stack/config.toml

各サービスには絶対パスの working_dir が設定され、モノレポや分散レイアウトに対応します。

セキュリティ

• .env は変数名のみを読み込みます。値が保存または表示されることはありません。
• 機密ファイル（.env、credentials.json、秘密鍵、secrets.*）は、分析および MCP から除外されます。
• security.rs の一元管理された拒否リストが、すべてのファイル読み取り経路を対象とします。

ライセンス

このプロジェクトは Apache License 2.0 のライセンスに基づいています。詳細については LICENSE ファイルをご覧ください。