The Problem

Organizations and individuals needing AI-assisted workflows face a choice between cloud-dependent agents that transmit sensitive data externally or isolated tools with limited functionality. Ghost addresses this by providing a private, local-first agent OS that indexes files, runs AI agents, and connects to 10,000+ tools via open protocols (MCP, AG-UI, A2UI, A2A) without any cloud dependency or telemetry.

What This Does

Ghost is a desktop and mobile agent OS that runs entirely on-device. It indexes files using FTS5 keyword search and sqlite-vec semantic search (<5ms and <500ms respectively), with Reciprocal Rank Fusion for combined results. The AI layer auto-detects CPU/RAM/GPU and selects optimal Qwen2.5-Instruct GGUF models (0.5B–7B, Q4_K_M) via Candle, with a fallback chain to Ollama HTTP. The complete 2026 agent protocol stack (MCP, AG-UI, A2UI, A2A) enables connection to diverse AI ecosystems without vendor lock-in. Fourteen high-impact and sixteen medium findings from static analysis indicate significant code health concerns alongside the functional capabilities.

How It Is Wired

Execution begins at run in src-tauri/src/agent/executor.rs:81, which reaches 90 functions and is the sole entry point with no callers within the repo. The traced path flows: run → generate_native [model via native agent inference] — this is the shortest path to an effect leaving the process. The most connected module is src/lib/types with Ca=14, Ce=0, instability 0, serving as a high-blast-radius hub that 14 modules depend on. src-tauri/src/protocols/runtime_bootstrap.rs routes through 124 functions across 7 callers, defining fmt, new, runtimes_dir, detect_all, and get_status. The entry point run touches a model for inference, reads/writes files, runs external commands, and makes outbound network calls — the model inference path being the primary external effect. Five functions stand out as called from the most distinct places: path (57 callers), get_catalog (40), get_app_data_dir (24), with_conn (24), and ok (20). The hub module src/lib/types.ts carries high blast-radius risk — changes ripple across 14 dependent modules.

How To Use It

Setup: No build command is documented beyond the presence of package.json (npm) and src-tauri/Cargo.toml (Rust). The repository requires Rust toolchain and Node.js dependencies installed from the committed package-lock.json.

Configuration: Environment variables and keys are not explicitly documented in the analyzed structure. The CLAUDE.md, CONTRIBUTING.md, and PRODUCT.md files in the root may contain configuration guidance, but no evidence of required env vars was found in the static analysis.

Running it: The primary entry point is the run function in src-tauri/src/agent/executor.rs:81. No CLI script or server start command is mapped in the analysis; invocation method is unspecified.

Real-World Use

A user searches across 50+ code formats (PDF, DOCX, XLSX, TXT, Markdown) via the native file watcher. The system returns fused keyword and semantic results in under 500ms. The user invokes a ReAct agent that reasons, calls a tool via one of the 10,000+ connected tools through the MCP/A2A protocol stack, observes the result, and iterates — all within the local process. If the hardware lacks GPU support, the system gracefully falls back to CPU-optimized GGUF models or offline mode without functionality loss.

Code Health & Issues

  • MEASURED FINDINGS (30 total): 14 high cognitive_load findings including deep nesting in src/components/McpAppStore.tsx, src-tauri/src/agent/executor.rs, and src-tauri/src/agent/skills.rs (max indentation depth 9); 8 oversized files exceeding practical readability thresholds; duplicated 6-line blocks across 11 files including src/components/McpAppStore.tsx, src/components/Settings.tsx, src/lib/tauri.ts, and src/lib/types.ts; high branching density (88 branch points over 304 lines) in src/hooks/useAgui.ts and src-tauri/src/embeddings/native.rs; and hub module concentration at src/lib/types.ts with 14 dependent modules.
  • CODE HEALTH AUDIT (7 findings): 4 high severity — unpinned GitHub Actions to commit SHAs (.github/workflows), missing test suite (71 source files, zero tests), discarded exit codes in ghost.yml (line 546), and PR-required commits on website-deploy.yml; 2 medium — installing from lockfile in CI versus npm install, and persist-credentials: false missing on checkout in website-deploy.yml; 1 low — missing timeout-minutes on workflow jobs in labeler.yml.

The Bottom Line

Ghost delivers on its core promise of a fully private, local-first agent OS with genuine protocol-stack breadth and search-performance claims that hold up under scrutiny. The codebase shows the wear of rapid feature accumulation: no test coverage, deeply nested control flow, and CI hygiene gaps that risk production regressions unnoticed. It is suitable for privacy-conscious users who need protocol interoperability and can tolerate untested code paths, but the engineering rigor does not yet match the ambitious scope.