Void Stack

Void Stack

Got 10 projects with backends, frontends, workers, and databases — and you can't remember how to start any of them? And your AI agent reads half the repo before it understands one?

Void Stack fixes both:

• One command starts your whole dev stack — backend, frontend, database, Docker, WSL. No memorizing ports or commands, no opening 5 terminals, no reading outdated READMEs.
• A local context engine for AI agents, over MCP — hybrid search (BM25 + exact vector search + a Tree-sitter call graph), project map and entry points. To understand a project at the same depth, your agent reads about 91 % less text than reading the files by hand (measured).

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

That's it. Void Stack scans your project, detects which frameworks you're using (FastAPI, Vite, Express, Django...), generates the right commands, and runs them. If there's a Python venv, it finds it. If node_modules is missing, it tells you.

High Performance — Built with Rust. Zero runtime overhead, instant startup, minimal memory footprint.

Agentic Workflow — MCP server with 75 tools lets Claude Desktop / Claude Code manage your services, search and map your code, check API contracts across projects, and audit security autonomously. Only need code context? void-stack-mcp --tools context exposes the 20 code-context tools and cuts tool definitions per session by 64 % (55,147 → 20,025 characters).

Cloud-Native Roadmap — Deploy to Vercel, DigitalOcean, and more from the same config (coming soon).

Leer en español | void-stack.dev

---

Dogfooding: Void Stack analyzes itself

Void Stack's own analysis and audit tools are used to maintain the quality of its codebase. Here's what running void analyze void-stack --compare and void audit void-stack on the project itself revealed — and how we used those findings to improve the code:

Security audit

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

The initial audit found 6 issues (risk score 25/100), but 4 were false positives — regex patterns and templates in the detection code flagged as "secrets". This led us to add smart false-positive filtering (self-referencing file allowlist, regex metacharacter detection, template line filtering), dropping the false positive rate from 83% to 0%.

Code analysis

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)

Findings that drove refactoring:

Finding	Action taken
God Class: cli/main.rs (1202 LOC, 25 fn)	Split into 6 command modules (~250 LOC main)
God Class: mcp/server.rs (1197 LOC, 35 fn)	Split into 10 tool modules (~340 LOC server)
God Class: manager.rs (30 fn)	Split into 4 submodules (process, state, logs, url)
God Class + Fat Controller: vuln_patterns.rs (789 LOC)	Split into 5 category modules (injection, xss, network, crypto, config)
God Class: db_models.rs (1065 LOC)	Split into 7 submodules by DB format (python, sequelize, gorm, drift, proto, prisma)
God Class: generate_dockerfile.rs (821 LOC)	Split into 6 submodules by language (python, node, rust, go, flutter)
God Class: api_routes.rs (747 LOC)	Split into 5 submodules by protocol (python, node, grpc, swagger)
God Class: architecture.rs (788 LOC)	Split into 4 submodules (externals, crates, infra)
God Class: classifier.rs (759 LOC, 44 fn)	Split into 3 submodules (logic, signals/data tables, tests)
Fat Controller: cli/analysis.rs (580 LOC)	Split into 4 submodules (analyze, diagram, audit, suggest)
CC=42: analyze_best_practices	Table-driven linter registry (CC ~15)
CC=41: cmd_analyze	Extracted 11 helper functions (CC ~10)

Technical debt tracking

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)

New in v0.22.0: explicit debt markers (TODO/FIXME/HACK/XXX/OPTIMIZE/BUG/TEMP/WORKAROUND) are now scanned from source comments and shown in CLI output, markdown reports, and the desktop Debt tab. Complex functions (CC≥10) are cross-referenced with coverage data — uncovered critical functions get [!] warnings in CLI and 🔴 indicators in markdown.

---

Hybrid Context Engine — Semantic + Structural

Most AI tools force you to choose: semantic search (find related concepts) OR structural graphs (trace call chains). Void Stack combines both. Vector embeddings find what is conceptually related. Tree-sitter graphs show what structurally breaks. The result: surgical context that no single-approach tool can match.

Approach	Query	Result
Semantic only	"auth middleware flow"	Conceptually related chunks
Structural only	"callers of validateToken"	Direct call chain
Hybrid (Void Stack)	Both simultaneously	Related chunks + blast radius

Void Stack indexes your codebase locally with BAAI/bge-small-en-v1.5 embeddings and builds a Tree-sitter call graph — so your AI assistant reads only what matters instead of scanning every file.

How it works

# 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)

Results are compact by default — location, symbol and the lines that match — and a hit already sent on the same connection comes back compact with a ↺ mark instead of whole (never hidden: subagents sharing one connection still see it). Import-only blocks are skipped; tests, docs and changelogs rank lower unless the query asks for them.

Search is hybrid by default: BM25 (SQLite FTS5, snake_case identifiers kept whole) fused with vector results via Reciprocal Rank Fusion — exact identifiers like stop_unix_process_group hit even when embeddings miss them. Modes: hybrid | vector | lexical.

0.36 vs 0.35 (Windows, 70 registered projects, same queries through the MCP server)

Measure	0.35	0.36	Change
Understanding a project (morrocoy, a 430-file Flutter app): the same 5 questions	10,586 chars	10,556 chars	−91 % vs 114,236 chars reading the 13 needed files by hand
get_api_contracts iunci (Flutter)	410,176 chars	33,222 chars	−92 %
get_api_contracts iunci-backend (Go)	234,464 chars	30,527 chars	−87 %
list_entrypoints iunci	23,139 chars, 41 real routes	4,701 chars, 97 real routes	−80 % (1,475 vendored .proto copies removed)
check_contracts (average of 3 projects)	20.5 s	0.89 s	23× faster
Tool definitions per session (0.36 with --tools context)	55,147 chars	20,025 chars	−64 %
build_structural_graph morrocoy	2.9 s	0.8 s	faster

With project_map + list_entrypoints added to those 5 questions the total is 18,055 characters (−84 % vs by hand), and it lists the app's 70 MCP tools. In 0.33 the same 5 questions returned ~49,000 characters (estimated, on an earlier machine). check_contracts got faster because files whose size and modification time didn't change are skipped without re-reading them, and producers are scanned in parallel.

Indexing on the GPU (new in 0.36; Windows, DirectML, RTX 4070 Ti SUPER):

Project	Chunks	CPU	GPU	Speed-up
iunci	12,206	740–1,003 s	73–75 s	~10–13×
void-stack	6,467	623 s	40 s	~16×
morrocoy	1,371	101–281 s	22 s (38 s the first run of a new binary, while DirectML compiles its shaders)	—

Embeddings are identical to the CPU's (cosine 1.000000 on all 12,206 chunks) and searches return the same results.

0.35 vs 0.34 (11 real projects, same machine, same queries through the MCP server)

Session	0.34 tokens	0.35 tokens	Less
"List every feature" (map + entry points + 8 searches), 8 projects	177,136	48,586	3.6×
140 searches mined from git history (7 projects)	332,233	60,494	5.5×
Same 4 questions asked twice in a session	37,992	4,358	8.7×
Cross-project (3 topics × 3 projects + cross GraphRAG + contracts)	109,391	7,833	14×

Same retrieval quality or better (hit@5 0.679 → 0.686, recall@5 0.514 → 0.538 on the 140 git-history queries), noisy hits in the top 5 (tests, import-only blocks, changelogs) 180 → 54, search latency unchanged (p50 ~10 ms), and project_map found all 21 packages of a 21-crate workspace where the search-only inventory surfaced 8. Indexing time and peak RAM are the same as 0.34. void bench <project> --task queries.txt reproduces the per-query numbers.

Benchmarks (measured on void-stack itself)

Operation	Without index	With void-stack	Reduction
semantic_search (avg)	~170 lines / file	~4 lines / result	97.5 %
Understanding a module	5-10 file reads	1 search query	~10x
Blast radius of a change	Manual, hours	get_impact_radius	instant

97.5 % figure reported by void stats --days 90 across 135 semantic_search operations — 23 868 lines of source that never entered the LLM context.

Footprint (v0.33, Windows, indexing void-stack from scratch, ~3,000 chunks): ~110 s and ~650 MB peak RAM, down from 193 s and 4.2 GB in v0.31. Vector search is exact (int8 vectors, recall 1.0) and the index takes 7.3 MB in memory. Details in the CHANGELOG.

GPU indexing (0.36): on Windows, void index embeds on the GPU through DirectML (any DirectX 12 GPU: NVIDIA, AMD, Intel) with no extra install, and falls back to the CPU if there is none. Searches keep embedding the query on the CPU (a few ms). VOID_STACK_EMBED_DEVICE=cpu forces the CPU. The GPU batch defaults to 32 (VOID_STACK_EMBED_BATCH overrides it; batch 32 used +2.5 GB of video memory, 128 used +8.8 GB for the same speed). macOS and Linux index on the CPU for now. After indexing, the CLI prints embeddings: GPU (DirectML) or embeddings: CPU.

Supported languages

• Semantic index (embeddings): every source extension in 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, plus md/proto/sql/dockerfile.
• Structural graph (Tree-sitter): Rust, Python, JavaScript, TypeScript (+ TSX), Go, Dart, Java, PHP, C, C++, Elixir, C#, Swift, GDScript, MQL4/MQL5 (C++ grammar).
• Dependency graph (imports): Python, JS/TS, Go, Dart, Rust, Verse, C#, Swift, GDScript, C/C++, MQL4/MQL5 — C# links using to the files declaring that namespace, Swift links import to the SwiftPM target, GDScript resolves res:// paths and class_names, C/C++ resolves #include "…" like Unreal's module include paths, MQL resolves #include <…> against the terminal's Include/ folder.
• Game engines: Unity (C#), Unreal Engine (C++ / UEFN Verse) and Godot (GDScript / C#) projects are detected from their markers; their cache/build folders (Library/, Intermediate/, .godot/, …) are skipped by every scanner and offered for cleanup in the Space panel.
• MetaTrader: MQL4/MQL5 projects (.mq4/.mq5/.mqh, or an MQL4/MQL5 data folder) are detected; MetaEditor's UTF-16 sources are read transparently, terminal event handlers (OnInit, OnTick, OnCalculate, …) are never reported as dead code, and compiled .ex4/.ex5 files are excluded.

Structural analysis inspired by code-review-graph (MIT) — AST node mappings and BFS query logic reimplemented natively in Rust.

---

Interfaces

Void Stack has 4 interfaces — use whichever you prefer:

Interface	Description
CLI (void)	Fast commands from terminal
TUI (void-stack-tui)	Interactive terminal dashboard: services, analysis, security audit, debt, space
Desktop (void-stack-desktop)	Desktop app with GUI (Tauri + React) — Windows (.msi), macOS (.dmg), Linux (.deb)
MCP Server (void-stack-mcp)	Integration with Claude Desktop / Claude Code

End-to-end example: FastAPI + React in 30 seconds

Say you have a project with a FastAPI backend and a React frontend:

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

Installation

Binaries (recommended)

Download pre-built binaries from the Releases page — no Rust required.

Platform	File
Windows	.msi / .exe (NSIS)
macOS	.dmg
Linux	.deb / .AppImage

Claude Desktop Extension — Each release also includes .mcpb files (one per platform). Drop the .mcpb into Claude Desktop to install the MCP server with zero configuration.

Binaries include vector search — Pre-built binaries from Releases include semantic code search powered by BAAI/bge-small-en-v1.5 (local, no API key). The embedding model (~130MB) downloads automatically on first void index use. To build without vector search: cargo build --release -p void-stack-cli

macOS note: If you get "cannot be opened because the developer cannot be verified", run:

xattr -cr /Applications/Void\ Stack.app

From source (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

Prerequisites: Rust + Protobuf compiler (winget install Google.Protobuf on Windows)

Build from source

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)

Desktop app (Tauri)

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

Diff-centric workflow: test selection & LLM-ready review

Two tools shorten the implement → test → review loop on large codebases:

suggest_tests_for_diff — run only the tests that cover your diff. A reverse coverage map (test → BFS callees over the structural graph, cached in SQLite) maps changed symbols to covering tests, ranked by call distance, with an explicit uncovered list and ready-to-paste commands:

$ 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 — a compact (≤4k tokens) review payload for the current diff, designed as INPUT for an LLM reviewer: summary, audit findings on changed lines only (suppression-aware), blast radius with hop labels, test coverage, and 1-hop call context for the hottest symbols:

$ 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) ...

Workflow: after each batch of edits run the suggested tests (not the full suite); before each commit run review_diff and address Critical/High findings + the uncovered list. The skills/skill-void-stack skill encodes these rules for Claude Code sessions.

Security & trust model

Void Stack is a service launcher: the command strings in void-stack.toml (and in registered services) are executed verbatim through the platform shell (sh -c on Unix, cmd /c on Windows) with your privileges. That is by design — but it means project configs are trusted input.

• Never start services from a repository you haven't reviewed: a malicious void-stack.toml runs arbitrary code.
• The daemon asks for a one-time confirmation before executing the service commands of a newly loaded project. The approval is stored in your user config directory (~/.config/void-stack/trusted-projects.json on Linux, ~/Library/Application Support/void-stack/ on macOS) — never inside the project — and is bound to a hash of the exact command set, so any change to the commands re-prompts. Use void-daemon start --yes to approve non-interactively (CI, scripts).
• Review the listed commands before approving; delete the project entry from trusted-projects.json to be asked again.

Register in your MCP clients

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

Excluding files from analysis

Create .voidignore in your project root to exclude paths from void analyze:

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

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

Same syntax as .gitignore (simplified). Supports prefix paths, **/ glob suffixes, and directory names.

Features

• Multi-service — Start/stop all services together or individually
• Cross-platform — Windows (cmd), macOS, WSL (bash), Docker containers, SSH (future)
• Auto-detection — Scans directories and identifies Python, Node, Rust, Go, Flutter, Docker, Elixir, Unreal Engine / UEFN (.uproject, .uplugin, .verse), Unity (ProjectSettings/ProjectVersion.txt), Godot (project.godot) and Swift (Package.swift, .xcodeproj)
• Smart commands — Detects FastAPI, Flask, Django, Vite, Next.js, Express, Air (Go hot-reload) and generates the right command
• Pre-launch hooks — Automatically creates venvs, installs deps (pip install, npm install, go mod download) per service before starting. Works out of the box with no configuration
• Dependency checking — Verifies Python, Node, CUDA, Ollama, Docker, Rust, .env
• Live logs — Stdout/stderr from all services with automatic URL detection
• Kanban board — Git-versioned BOARD.md (CLI, MCP and desktop): per-task history and work timeline reconstructed from the board's git log in a single batched git read (fast even on Windows, where per-commit process spawns used to take seconds), including projects hosted in WSL (\\wsl.localhost\… roots route git through wsl.exe)
• Diagrams — Generates Mermaid and Draw.io from project structure using unified scanners (architecture, API routes with Swagger/OpenAPI enrichment, internal/external API separation, gRPC/Protobuf services, DB models with FK-proximity layout — Prisma, Sequelize, GORM, Django, SQLAlchemy, Drift)
• Code analysis — Dependency graphs, anti-patterns, cyclomatic complexity, coverage
• Best practices — Native linters (react-doctor, ruff, clippy, golangci-lint, dart analyze) with unified scoring
• Technical debt — Metric snapshots with trend comparison
• AI integration — MCP server with 75 tools for Claude Desktop / Claude Code; AI-powered refactoring suggestions via Ollama (local LLM) with graceful fallback. When a semantic index exists, enriches prompts with actual code snippets from complexity hotspots and god classes
• Semantic code search — Index any project locally with BAAI/bge-small-en-v1.5 embeddings (100 % offline, ~130 MB one-time download). void search and the semantic_search MCP tool return only the relevant chunks — 97.5 % fewer tokens than reading files directly (measured on void-stack's own codebase over 135 queries).
• Structural call graph — Tree-sitter powered function-level analysis for Rust, Python, JS, TS, Go, Dart, Java, PHP, C, C++ (incl. Unreal Engine), Elixir, C# (Unity / Godot .NET), Swift and GDScript (Godot). Verse (UEFN) is covered by the import analyzer, semantic index and debt scanners (no tree-sitter grammar exists for it yet). Persists to .void-stack/structural.db (or %LOCALAPPDATA%\void-stack\structural\<project>\ for WSL-hosted projects). Blast-radius BFS (get_impact_radius) answers "what breaks if I change this file?" before you touch a line.
• Incremental indexing — Git diff + SHA-256 hashing: --git-base HEAD~1 only re-indexes files actually changed since the last commit. watch_project (MCP) auto-reindexes on save with 500 ms debounce; install_index_hook (MCP) wires a post-commit hook so every commit keeps the index fresh.
• Disk space scanner — Scan and clean project deps (node_modules, venv, target) and global caches (npm, pip, Cargo, Ollama, HuggingFace, LM Studio)
• Desktop GUI — Tauri app with cyberpunk mission-control aesthetic, visual hierarchy (KPI cards, glow effects, severity gradients), services, logs, dependencies, diagrams, analysis, docs, security, debt, and disk space
• Daemon — Optional gRPC daemon for persistent management
• Security audit — Dependency vulnerabilities, hardcoded secrets, insecure configs, code vulnerability patterns (SQL injection, command injection, path traversal, XSS, SSRF, and more) with smart false-positive filtering (skips self-referencing detection patterns, regex definitions, templates, JSX elements, git history refactor commits, and test modules via brace-depth tracking)
• Docker Runner — Services with target = "docker" run inside Docker containers. Four modes: raw docker commands, image references (postgres:16 → auto docker run), Compose auto-detect, and Dockerfile builds. Compose imports as a single docker compose up service that launches all containers together. docker: prefix separates Docker services from local ones. Per-service config for ports, volumes, and extra args. Process exit watcher detects failures and updates status automatically
• Docker Intelligence — Parse Dockerfiles and docker-compose.yml, auto-generate Dockerfiles per framework (Python, Node, Rust, Go, Flutter), generate docker-compose.yml with auto-detected infrastructure (PostgreSQL, Redis, MongoDB, etc.)
• Infrastructure Intelligence — Detect Terraform resources (AWS RDS, ElastiCache, S3, Lambda, SQS, GCP Cloud SQL, Azure PostgreSQL), Kubernetes manifests (Deployments, Services, Ingress, StatefulSets), and Helm charts with dependencies — all integrated into architecture diagrams
• Security — Never reads .env values; centralized sensitive file protection

CLI

Command	Description
void add <n> <path> [--tag T]	Register project (auto-detects services)
void tag <project> [TAGS…] [--remove T] [--clear]	Mark a project as yours (own / propio) or someone else's (third-party / tercero), or add any label
void add-service <project> <n> <cmd> -d <dir>	Add service manually
void edit-service <project> <svc> [-c CMD] [-d DIR] [-t TARGET] [--rename N] [--enable|--disable]	Edit a service (e.g. fix an auto-detected command that doesn't work)
void remove-service <project> <svc>	Remove a service from a project
void remove <n>	Unregister project
void list [--tag T]	List projects and services (only those with a tag)
void scan <path>	Preview detection without registering
void start <project> [-s service]	Start all or one service
void stop <project> [-s service]	Stop all or one service
void status <project>	Live status: PIDs, URLs, uptime
void check <project>	Verify dependencies
void diagram <project> [-f mermaid|drawio] [--print-content]	Generate diagrams
void audit <project> [-o file]	Security audit
void analyze <project> [--compare] [--cross-project] [--best-practices]	Code analysis
void docker <project> [--generate-dockerfile] [--generate-compose] [--save]	Docker intelligence
void suggest <project> [--model <m>] [--service <s>] [--raw]	AI refactoring suggestions (Ollama)
void read-file <project> <path>	Read any project file (blocks .env, credentials)
void logs <project> <service> [-n lines] [--compact] [--raw]	Show filtered service logs
void index <project> [--force] [--generate-voidignore] [--git-base <ref>]	Index codebase for semantic search (--git-base HEAD~1 uses git diff)
void search <project> "<query>" [-t top_k] [--detail compact|full|auto]	Semantic code search (compact hits by default: location, symbol, matching lines)
void map <project> [--depth N]	Project map: packages, entry files, code per directory, key docs
void entrypoints <project> [--kind rest,grpc,mcp,cli,routes,jobs]	Every entry point: HTTP routes, RPCs, MCP tools, CLI commands, UI routes, jobs
void contracts check <project>	Consumed API routes/RPCs checked against the registered projects that serve them (non-zero exit on drift)
void bench <project> --task <file> [--json]	Tokens per query: compact output vs full chunks vs reading the files whole
void stats [--project <p>] [--days <d>] [--json]	Token savings statistics
void claudeignore <project> [--dry-run] [--force]	Generate .claudeignore optimized for tech stack

Flags: --wsl (WSL paths), --daemon (connect to daemon), --compare (compare snapshots), --cross-project (inter-project deps), --label <tag> (tag snapshot)

MCP-only tools (Claude Desktop / Claude Code / OpenCode)

These aren't CLI commands — they're exposed by void-stack-mcp:

Tool	Description
get_chunk	Expand a compact search hit: lines line_start..=line_end of a file
watch_project / unwatch_project	Auto re-index on file changes (~500 ms debounce)
install_index_hook	Install a post-commit hook that re-indexes changed files
build_structural_graph	Tree-sitter call graph across 14 languages — Rust, Python, JS, TS, Go, Dart, Java, PHP, C, C++, Elixir, C#, Swift, GDScript + MQL4/MQL5 (--features structural)
get_impact_radius	Blast-radius BFS — who/what is affected by changes to a file
query_graph	Callers / callees / tests / fuzzy-search over the structural graph
full_analysis	Combined audit + architecture + semantic hot-spots in one report (quick/standard/deep)
manage_suppressions	List / add / remove audit suppression rules without editing files manually
setup_project	One-click onboarding: register + generate ignores + index + audit + analyze

Structural analysis inspired by code-review-graph (MIT).

TUI Dashboard

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

Key	Action
a	Start all services
s	Start selected service
k	Stop selected service
K	Stop all
1-5	Switch tab (Services/Analysis/Security/Debt/Space)
R	Run action (analyze, audit, scan) on current tab
j/↓	Navigate down
l	Toggle log panel
Tab	Switch panel
r	Refresh status
L	Toggle language (ES/EN)
?	Help
q	Quit (stops services)

i18n: Spanish (default) and English. Press L to toggle.

Tabs: Services (manage/monitor), Analysis (architecture pattern, layers, anti-patterns, complexity + coverage cross-ref), Security (risk score, vulnerability findings), Debt (TODO/FIXME/HACK markers), Space (project + global disk usage)

Desktop (Tauri)

Desktop app with a four-zone shell (topbar + rail), a ⌘K command palette, and a project intelligence pulse line. Panels are grouped into Run (services, logs, docker), Intelligence (search, review, tests, dead code, analysis, security, debt), Map (graph, diagrams, stats) and Project (deps, docs, space).

• Topbar: Project picker with inline rename/move (preserves indexes) and quick-add, ⌘K command palette (services + actions + semantic-search fallback), index/graph freshness vitals (click to rebuild the graph), language toggle (ES/EN)
• Pulse line: One-line project intelligence — review findings, suggested/uncovered tests, dead-code count, audit risk — fetched in parallel and cached per project
• Services: Card grid with status dot, lang badge, port link (opens in browser), uptime, last log line, start/stop and remove; ghost "add service" card
• Logs: Structured viewer (level filters, search, follow mode, wrap/raw toggles, "impact" on error lines with a detected path) plus a collapsible drawer under the service grid
• Search: Semantic search, GraphRAG (semantic + structural call-graph) and cross-project GraphRAG from the UI; results open in your editor at the line
• Graph: In-app interactive dependency-graph viewer (Cytoscape) — node size by importance, neighborhood highlight, layout switcher, color-by layer/community; click a file to open it in VS Code / Cursor / Windsurf
• Diagrams: Mermaid + native Draw.io XML rendering (custom SVG renderer with DOMPurify) for architecture, API routes, DB models
• Analysis / Security / Debt: Architecture patterns, anti-patterns, complexity, coverage; risk score, vulnerability/secret findings; metric snapshots with trend comparison
• Docs / Disk Space / Docker: Markdown docs; scan + clean caches; parse/generate Docker artifacts and detect Terraform/Kubernetes/Helm
• UX: Geist + JetBrains Mono typography, focus-visible rings, reduced-motion support, educational tooltips, copy buttons

MCP Server (AI Integration)

Lets Claude Desktop, Claude Code, or OpenCode manage your projects directly.

Windows — Add to %APPDATA%\Claude\claude_desktop_config.json:

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

macOS — Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Linux — Add to ~/.config/Claude/claude_desktop_config.json:

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

OpenCode (free models — no API key required) — Add to ~/.config/opencode/opencode.json:

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

On macOS use the full path: ["~/.cargo/bin/void-stack-mcp"]

OpenCode advantage: Works with free models (MiniMax, Qwen, DeepSeek) — zero API cost, full void-stack MCP integration.

macOS note: Claude Desktop and OpenCode launch with a minimal PATH that doesn't include ~/.cargo/bin. Use the full absolute path to the binary. Run which void-stack-mcp in Terminal to get it. Also remove the quarantine flag or macOS will silently block the binary:

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

Remote clients: streamable HTTP (--http)

Every config above spawns the server over stdio — one process per client, on the same machine. --http serves the same tools over MCP streamable HTTP instead, so clients on another machine (or inside WSL) share one server and one project registry:

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

Register it from any MCP client that speaks HTTP — both / and /mcp work:

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

Typical use: run the server on Windows and consume it from WSL (with networkingMode=mirrored, localhost crosses over) or from another machine over Tailscale — the tools keep reading the registry of the host they run on, so all clients see the same projects.

No authentication. The HTTP transport has none by design: whoever can reach the port gets full access to your projects. Keep it on loopback or a tailnet — the server logs a warning at startup when the bind address is neither loopback nor a Tailscale range (100.64.0.0/10, fd7a:115c:a1e0::/48). Don't expose it to the open internet; put Tailscale (or an authenticating reverse proxy) in front of it.

One process serves stdio or HTTP, not both. Run a second process if you want both at once.

Fewer tools, fewer tokens (--tools)

Every client receives the definition of every tool in its context: all 75 are 55,147 characters per session. Expose only what a client needs with a profile, a comma-separated list of tool names, or both — --tools context cuts tool definitions per session by 64 % (55,147 → 20,025 characters):

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

Profiles: context (map, entry points, search, graph, contracts, docs), devops (projects, services, logs, dependencies, Docker), review (audit, analysis, debt, diff review, board). Default and full: every tool.

In a client config, pass the profile in args:

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

Available tools (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

Dependency Detection

Detector	Checks
Python	Binary, version, venv, pip check
Node	Binary, node_modules freshness
CUDA	nvidia-smi, driver, GPU, VRAM, PyTorch
Ollama	Binary, API health, downloaded models
Docker	Binary, daemon status, compose
Rust	rustc and cargo versions
Go	go version, go.mod presence
Flutter	flutter --version, dart --version, pubspec.yaml
.env	Compares .env vs .env.example

Code Analysis

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

• Patterns — MVC, Layered, Clean/Hexagonal with confidence
• Anti-patterns — God Class, Circular Dependencies, Fat Controllers, Excessive Coupling
• Cyclomatic complexity — Per-function (Python, JS/TS, Go, Dart, Rust)
• Coverage — LCOV, Cobertura, Istanbul, Go cover profiles
• Graphs — Mermaid diagrams of module relationships
• Trends — Historical snapshots with comparison

Diagrams

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

Detects: service architecture, external services (by URL extraction from source code and .env), internal service-to-service calls (localhost cross-referencing by port), API routes with Swagger/OpenAPI enrichment (FastAPI, Flask, Express, gRPC/Protobuf), internal vs public API separation, DB models (SQLAlchemy, Django, Prisma, Sequelize, GORM, Drift, Protobuf messages), Rust crate relationships.

Architecture

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

Configuration

void-stack.toml (per project)

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"]

Global config

All projects are stored in a platform-specific location:

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

Each service has an absolute working_dir, supporting monorepos and distributed layouts.

Security

• .env is read for variable names only — values are never stored or displayed
• Sensitive files (.env, credentials.json, private keys, secrets.*) blocked from analysis and MCP
• Centralized deny-list in security.rs covers all file-reading paths

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.