void-stack

<p align="center"> <img src="crates/void-stack-desktop/icons/icon.svg" alt="Void Stack" width="120" height="120"> </p> <h1 align="center">Void Stack</h1>

Got 10 projects with backends, frontends, workers, and databases — and you can't remember how to start any of them?

Void Stack fixes that. One command to start your entire dev stack — backend, frontend, database, workers — on Windows, WSL, or Docker. No memorizing ports, no opening 5 terminals, no reading outdated READMEs.

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 43 tools lets Claude Desktop / Claude Code manage your services, analyze code, and audit security autonomously.

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

Leer en español | void-stack.dev

<div align="center"> <img src="https://github.com/user-attachments/assets/77be9712-0263-4625-953d-5c6163b4de09" alt="Void Stack Desktop — services running" width="100%"/> <br/><br/> <img src="https://github.com/user-attachments/assets/817b3b04-9347-4bc0-a374-8708694b37fe" alt="Void Stack TUI — navigating tabs" width="80%"/> </div>

---

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)
# 2110 tests passing across the workspace

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

# Search by concept, not by filename
void search my-project "authentication middleware flow"
# Returns the 3-5 most relevant code chunks — not the whole file

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

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.

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.

Supported languages

• Semantic index (embeddings): every source extension in CODE_EXTENSIONS — Rust, Python, JS/TS, Go, Dart, Java, PHP, C/C++, Ruby, Swift, Kotlin, Lua, Zig, Elixir, Vue, Svelte, Astro, plus md/proto/sql/dockerfile.
• Structural graph (Tree-sitter): Rust, Python, JavaScript, TypeScript (+ TSX), Go, Dart, Java, PHP, C, C++, Elixir.

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 s