Void Stack

Void Stack

[![CI](https://github.com/Mague/void-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/Mague/void-stack/actions/workflows/ci.yml) [![Release](https://github.com/Mague/void-stack/actions/workflows/release.yml/badge.svg)](https://github.com/Mague/void-stack/actions/workflows/release.yml) [![Version](https://img.shields.io/github/v/release/Mague/void-stack?include_prereleases&label=version)](https://github.com/Mague/void-stack/releases/latest) [![License](https://img.shields.io/github/license/Mague/void-stack)](LICENSE) [![Rust](https://img.shields.io/badge/rust-2024%20edition-orange)](https://www.rust-lang.org/) [![Tests](https://img.shields.io/badge/tests-2313%20passing-brightgreen)]() [![Coverage](https://img.shields.io/badge/coverage-83.0%25-brightgreen)]() **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). ```bash 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](README.es.md)** | **[void-stack.dev](https://void-stack.dev)**
Void Stack Desktop — services running

Void Stack TUI — navigating tabs
--- ## 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 ```bash 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 ```bash 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 ```bash 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 ```bash # 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 --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](CHANGELOG.md). **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_name`s, 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](https://github.com/tirth8205/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 ``` ```bash # 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](https://github.com/mague/void-stack/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: > ```bash > xattr -cr /Applications/Void\ Stack.app > ``` ### From source (Cargo) ```bash # 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](https://rustup.rs) + Protobuf compiler (`winget install Google.Protobuf` on Windows) ### Build from source ```bash 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) ```bash 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 ```bash 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\\` 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 [--tag T]` | Register project (auto-detects services) | | `void tag [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 -d ` | Add service manually | | `void edit-service [-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 ` | Remove a service from a project | | `void remove ` | Unregister project | | `void list [--tag T]` | List projects and services (only those with a tag) | | `void scan ` | Preview detection without registering | | `void start [-s service]` | Start all or one service | | `void stop [-s service]` | Stop all or one service | | `void status ` | Live status: PIDs, URLs, uptime | | `void check ` | Verify dependencies | | `void diagram [-f mermaid\|drawio] [--print-content]` | Generate diagrams | | `void audit [-o file]` | Security audit | | `void analyze [--compare] [--cross-project] [--best-practices]` | Code analysis | | `void docker [--generate-dockerfile] [--generate-compose] [--save]` | Docker intelligence | | `void suggest [--model ] [--service ] [--raw]` | AI refactoring suggestions (Ollama) | | `void read-file ` | Read any project file (blocks .env, credentials) | | `void logs [-n lines] [--compact] [--raw]` | Show filtered service logs | | `void index [--force] [--generate-voidignore] [--git-base ]` | Index codebase for semantic search (`--git-base HEAD~1` uses git diff) | | `void search "" [-t top_k] [--detail compact\|full\|auto]` | Semantic code search (compact hits by default: location, symbol, matching lines) | | `void map [--depth N]` | Project map: packages, entry files, code per directory, key docs | | `void entrypoints [--kind rest,grpc,mcp,cli,routes,jobs]` | Every entry point: HTTP routes, RPCs, MCP tools, CLI commands, UI routes, jobs | | `void contracts check ` | Consumed API routes/RPCs checked against the registered projects that serve them (non-zero exit on drift) | | `void bench --task [--json]` | Tokens per query: compact output vs full chunks vs reading the files whole | | `void stats [--project

] [--days ] [--json]` | Token savings statistics | | `void claudeignore [--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 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](https://github.com/tirth8205/code-review-graph) (MIT). ## TUI Dashboard ```bash 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`: ```json { "mcpServers": { "void-stack": { "command": "void-stack-mcp.exe" } } } ``` **macOS** — Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "void-stack": { "command": "/Users/YOUR_USERNAME/.cargo/bin/void-stack-mcp" } } } ``` **Linux** — Add to `~/.config/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "void-stack": { "command": "void-stack-mcp" } } } ``` **OpenCode** (free models — no API key required) — Add to `~/.config/opencode/opencode.json`: ```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: > ```bash > 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: ```bash 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: ```bash 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): ```bash 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`: ```json { "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 ```bash 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 ```bash 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) ```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"] ``` ### 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](LICENSE). See the LICENSE file for details.