npm package: @precisionutilityguild/liquid-shadow
Description: Tactical Repository Intelligence Operative - Liquid Shadow Ecosystem
Author: Precision Utility Guild
Latest version: 1.0.11

<p align="center">
  <img src="https://img.shields.io/badge/%F0%9F%8C%91_Liquid_Shadow-MCP_Intelligence_Layer-6D28D9?style=for-the-badge" alt="Liquid Shadow">
</p>

<h1 align="center">Liquid Shadow</h1>

<p align="center">
  <strong>The AI-First Code Intelligence Layer for MCP Agents</strong><br>
  Stop making your agents grep. Give them a brain.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@precisionutilityguild/liquid-shadow"><img src="https://img.shields.io/npm/v/@precisionutilityguild/liquid-shadow?color=6D28D9&label=npm" alt="npm version"></a>
  <img src="https://img.shields.io/badge/MCP-Compatible-10B981.svg" alt="MCP Compatible">
  <img src="https://img.shields.io/badge/Tools-52_Atomic-F59E0B.svg" alt="52 Tools">
  <img src="https://img.shields.io/badge/Languages-TS%20%7C%20JS%20%7C%20Python%20%7C%20PHP%20%7C%20Go-3B82F6.svg" alt="Languages">
  <img src="https://img.shields.io/badge/License-Apache--2.0-gray.svg" alt="License">
</p>

---

## The Problem With How Agents Work Today

Every time your AI agent needs to understand a codebase, it does this:

```
read file → grep → read another file → grep → read another file...
```

That's hundreds of tokens, dozens of tool calls, and a reasoning chain that collapses under its own weight for anything larger than a toy project. The agent never builds a real mental model — it just stumbles through the dark.

**Liquid Shadow fixes this at the architecture level.**

---

## What It Is

Liquid Shadow is a **Model Context Protocol (MCP) server** that builds a persistent **Relational Intelligence Graph** of your codebase — symbols, dependencies, types, execution flows, git history — and exposes it as 52 high-signal atomic tools your agents can use instead of file reads and grep.

One `shadow_analyze_flow` call returns the entire execution graph from an entrypoint.  
One `shadow_analyze_impact` call shows the full blast radius before a change.  
One `shadow_ops_briefing` call resumes mission context across sessions.

This isn't a smarter `grep`. It's a different paradigm entirely.

---

## What It Actually Does

### 🔍 Semantic Code Discovery
Natural language search across your entire codebase. Find "authentication logic" — not just files with `auth` in the name. Powered by hybrid **vector + BM25 FTS** search with Reciprocal Rank Fusion scoring.

### 📊 Relational Graph Analysis
Trace full execution flows. Compute blast radius of any change. Resolve type inheritance chains. Map every HTTP route, socket event, and pubsub topic — producers and consumers split.

### 🧠 Token-Optimized Inspection
The **Semantic Sieve** folds implementation details and surfaces only signatures and intent. Control depth with `Orbit → Atmosphere → Ground` zoom levels. A file summary costs ~20 tokens instead of 2,000.

### 🎯 Mission-Driven Development
Persistent context that **survives across sessions**. Create missions with outcome contracts, log decisions and discoveries, synthesize Architectural Decision Records, and resume exactly where you left off — even weeks later.

### 🤝 Multi-Agent Coordination
File-level **claim/release locking** prevents parallel agents from stomping on each other's work. Dispatch plans across agent roles. Submit findings to a peer-review Tribunal. Hand off typed artifacts between RECON → OVERSEER → ENGINEER pipelines.

### 🔧 Zero-Maintenance Indexing
Git hooks auto-reindex on every commit and branch switch. The **Ember Daemon** builds semantic embeddings in the background at lowest OS priority — your `git commit` is never blocked.

### 🌐 Cross-Repo Intelligence
The **Fused Index** unifies multiple repositories at query time via SQLite `ATTACH DATABASE`. Zero data duplication. Trace a frontend API call all the way through to the backend handler across repo boundaries.

---

## Tool Suite (52 Atomic Tools)

| Suite | Tools | Purpose |
|:------|:------|:--------|
| **`shadow_recon_*`** | `onboard` `topography` `scout` `tree` `hologram` | Bootstrap index, structural classification, arc maps |
| **`shadow_search_*`** | `concept` `symbol` `config` `path` | Semantic, symbol, env var, and path searches |
| **`shadow_analyze_*`** | `impact` `flow` `deps` `mesh` `type_graph` `debt` `explain_diff` | Blast radius, execution flows, API surfaces, dead code, diff narratives |
| **`shadow_inspect_*`** | `symbol` `file` | Token-folded symbol inspection and file summaries |
| **`shadow_ops_*`** | `plan` `track` `log` `briefing` `context` `synthesize` `chronicle` `health` `graph` `crystallize` `crystallize_theme` `claim` `release` `dispatch_plan` `tribunal_submit` `tribunal_status` `handoff` `handoff_read` | Full mission lifecycle + multi-agent coordination |
| **`shadow_sync_*`** | `trace` `index` `repair` | Incremental sync, Nano-Repair auto-healing |
| **`shadow_env_*`** | `hooks` `diagnose` | Git hook management, system health |
| **`shadow_workspace_*`** | `list` `link` `fuse` `status` `ensure` `repair` `gc` | Multi-repo Federation |

---

## Zero-Config Setup (2 Minutes)

Stop configuring things manually. Liquid Shadow auto-discovers your IDE and injects both the MCP server and the Tactical Skills so your agent is instantly operational.

```bash
# 1. Install globally
npm i -g @precisionutilityguild/liquid-shadow

# 2. Run the tactical onboarding
liquid-shadow init
```

The `init` script automatically configures MCP connections for:
- ✅ **Claude Code** (`~/.claude.json`)
- ✅ **Claude Desktop** (`claude_desktop_config.json`)
- ✅ **Gemini CLI** (`~/.gemini/settings.json`)
- ✅ **Antigravity IDE** (`mcp_config.json`)
- ✅ **Cursor** (via `.cursor/mcp.json` context)
- ✅ **Codex** (`~/.codex/config.toml`)

*(If you are using an unsupported client, simply point it to `liquid-shadow-mcp` with no arguments).*

---

## First Run: Onboard Your Repository

Once connected, tell your agent:

```
Use shadow_recon_onboard on /absolute/path/to/your/repo
```

Liquid Shadow scans all source files, extracts symbols, builds dependency graphs, and fires up the Ember Daemon for background embedding generation. Most mid-size projects are ready in under 30 seconds.

---

## The Skills System

Liquid Shadow ships **14 pre-built agent workflows** (called Skills) that are automatically injected into your agent's context on `init`. Instead of calling raw tools and guessing at the right sequence, agents follow optimized tactical playbooks.

| Skill | What It Does |
|:------|:-------------|
| `/onboard` | Bootstrap index, hooks, and first mission |
| `/understand` | Concept-to-code mapping and execution tracing |
| `/mission` | Strategic planning with outcome contracts |
| `/continue` | Resume the highest-priority active mission |
| `/trace-impact` | Blast radius and cross-repo dependency maps |
| `/audit` | Dead code, circular deps, layer drift detection |
| `/chronicle` | Git-native narrative history of the project |
| `/synthesize` | Distill mission logs into Architectural Decision Records |
| `/research` | External dependency research with local + web context |
| `/workspace` | Multi-repo federation and mission linking |
| `/crystallize` | Compress mission logs for token-efficient briefings |
| `/coordinate` | Multi-agent dispatch and Tribunal reviews |
| `/sync` | Incremental index repair after external changes |

Skills reduce "what tools do I call in what order?" from a guessing game to a single directive.

---

## Real Usage Patterns

### "What breaks if I change this function?"

```
Use shadow_analyze_impact on the authenticateUser function in src/auth/service.ts
```

Returns: every downstream consumer, call depth by default = 3, with file paths and symbol names. Blast radius computed in one call.

### "Where is the auth logic?"

```
Use shadow_search_concept to find all authentication and session handling code
```

Returns: semantically ranked results. Finds code that *handles auth* even if it doesn't have `auth` in the filename.

### "Explain what changed in this diff"

```
Use shadow_analyze_explain_diff with staged:true
```

Returns: a semantic narrative of what your current staged changes actually do — not just a list of lines changed.

### "Resume where I left off"

```
Use shadow_ops_briefing on /path/to/repo at Ground altitude
```

Returns: active missions, next candidates, recent decisions, health stats — full context reconstruction from persistent storage.

### "Find all API endpoints in this service"

```
Use shadow_analyze_mesh on /path/to/repo with topic "/api/"
```

Returns: every HTTP route, socket event handler, and pubsub topic — producers and consumers mapped separately.

---

## Performance

Indexing is CPU-parallel via SWC worker pools. Semantic embeddings are off-thread via the Ember Daemon.

| Repository | Files | Symbols | Time |
|:-----------|:------|:--------|:-----|
| VS Code core | 6,100 | 109,000+ | 110.6s |
| Next.js | 9,700 | — | 24.2s (~400 files/sec) |
| Django | 2,893 | — | validated |
| Laravel Framework | 2,854 | — | validated |
| FastAPI | 1,118 | — | validated |

After the first index, incremental syncs typically complete in 1–3 seconds.

---

## CLI Reference

For direct terminal use without an agent:

```bash
# Initialize the intelligence index
npx @precisionutilityguild/liquid-shadow index /path/to/repo

# Real-time dashboard
npx @precisionutilityguild/liquid-shadow dashboard

# Quick status
npx @precisionutilityguild/liquid-shadow status /path/to/repo

# Symbol inspection
npx @precisionutilityguild/liquid-shadow inspect symbol /path/to/repo MyClass

# Mission management
npx @precisionutilityguild/liquid-shadow mission plan /path/to/repo "Migrate Auth" "Replace JWT with OAuth2"
npx @precisionutilityguild/liquid-shadow mission briefing /path/to/repo
npx @precisionutilityguild/liquid-shadow mission synthesize /path/to/repo <mission-id>

# Semantic search
npx @precisionutilityguild/liquid-shadow search-concept "authentication middleware"

# Deploy/update skills to all detected agents
npx @precisionutilityguild/liquid-shadow skills update

# Git hooks (auto-reindex on commit + branch switch)
npx @precisionutilityguild/liquid-shadow hooks install
```

---

## Supported Languages

| Language | Parser | Status |
|:---------|:-------|:-------|
| TypeScript | SWC | ✅ Full |
| JavaScript | SWC | ✅ Full |
| Python | Tree-sitter | ✅ Full |
| PHP | Tree-sitter | ✅ Full |
| Go | Tree-sitter | ✅ Full |

More languages are added via Tree-sitter grammars. The parser is auto-selected from file extension.

---

## Architecture at a Glance

```
Your Agent (Claude / Cursor / Gemini / etc.)
         │
         │  MCP stdio transport
         ▼
┌─────────────────────────────────────────┐
│           Liquid Shadow MCP Server      │
│  52 atomic tools across 8 suites        │
│                                         │
│  ┌──────────┐  ┌──────────────────────┐ │
│  │  Recon   │  │  Intelligence Engine │ │
│  │  Layer   │  │  (Impact/Flow/Mesh)  │ │
│  └────┬─────┘  └──────────┬───────────┘ │
│       │                   │             │
│  ┌────▼───────────────────▼───────────┐ │
│  │   SQLite FTS5 + Vector Index       │ │
│  │   (Symbols · Deps · Embeddings)    │ │
│  └────────────────────────────────────┘ │
│                                         │
│  ┌──────────────┐  ┌────────────────┐   │
│  │ Mission Store│  │  Ember Daemon  │   │
│  │ (Git Notes)  │  │ (bg embeddings)│   │
│  └──────────────┘  └────────────────┘   │
└─────────────────────────────────────────┘
         │
         ▼
  Your Repository (read-only — never modifies source)
```

Liquid Shadow is **fully read-only** on your source code. It maintains its own SQLite index alongside your repository.

---

## Multi-Agent & Parallel Safety

Running multiple agents on the same codebase simultaneously? Liquid Shadow handles it:

- **`shadow_ops_claim`** — agent claims a file before editing
- **`shadow_ops_release`** — releases the claim after
- **`shadow_working_set_check`** — query active claims before spawning parallel workers
- **`shadow_ops_dispatch_plan`** — assign sub-missions to specialized agent roles
- **`shadow_ops_tribunal_submit/status`** — peer-review findings before merging conclusions

Claim entries are TTL-based and auto-expire, so a crashed agent never permanently blocks a file.

---

## Frequently Asked Questions

**Does Liquid Shadow modify my source code?**  
Never. It is strictly read-only on your codebase. The only files it writes are its own SQLite index and Git Notes for mission logs.

**How do I keep the index fresh?**  
You don't have to. Every tool automatically runs a JIT (Just-In-Time) git-tree differential check before executing. If you've modified files since the last index, it incrementally syncs only the changed files in milliseconds before answering your query. (You can also install Git hooks via `shadow_env_hooks` for background syncing).

**What if I rename files or move symbols?**  
Run `shadow_sync_repair`. Nano-Repair re-links anchors and heals broken intent references without a full re-index.

**Can I use this as a library (not MCP)?**  
Yes. The programmatic API (`query.ts`) exposes `searchSymbol`, `analyzeImpact`, and `getBriefing` as direct TypeScript entry-points.

**Does it work offline / on private code?**  
Yes. Everything runs locally. No source code is sent anywhere. Embeddings are generated locally via `@xenova/transformers`.

---

## Links

- **Homepage**: [liquidshadow.pugcorp.online](https://liquidshadow.pugcorp.online/)
- **npm**: [@precisionutilityguild/liquid-shadow](https://www.npmjs.com/package/@precisionutilityguild/liquid-shadow)
- **GitHub**: [PrecisionUtilityGuild/liquid-shadow](https://github.com/PrecisionUtilityGuild/liquid-shadow)
- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)

---

<p align="center">
  Built on <b>SQLite FTS5</b> · <b>SWC</b> · <b>Tree-sitter</b> · <b>@xenova/transformers</b><br>
  <i>Precision Utility Guild — making agents smarter, not louder.</i>
</p>