LoomMCP

The universal context compiler for AI coding agents. 97.75% token reduction, GPU embeddings, compact wire format. Free forever — no enterprise license required.

🌐 Live Website · 📦 npm · ⭐ GitHub

🎥 Demo

See LoomMCP compress a real-world codebase in seconds:

Watch LoomMCP in action

Structured code retrieval for serious AI agents

LoomMCP ships with a full observability dashboard at http://localhost:2337 — no extra setup required.

Documentation

Cut code-reading token usage by 97.75% or more

Most AI agents explore repositories the expensive way:

open entire files → skim thousands of irrelevant lines → repeat.

That is not "a little inefficient." That is a token incinerator.

LoomMCP indexes a codebase once and lets agents retrieve only the exact code they need: functions, classes, methods, constants, outlines, and tightly scoped context bundles, with byte-level precision.

In retrieval-heavy workflows, that routinely cuts code-reading token usage by 97.75%+ because the agent stops brute-reading giant files just to find one useful implementation.

Index once. Query cheaply. Keep moving. Precision context beats brute-force context.

Compact output — the second token axis (LOOM)

Retrieval decides what to send. LOOM decides how to pack it.

Every tool response can be emitted in a purpose-built compact wire format instead of verbose JSON. Path prefixes are interned to short handles, homogeneous lists of dicts pack into single-character-tagged CSV rows, and per-column types are preserved so the decode is lossless.

// Any tool call accepts format=
loom_get_symbol({ symbol: "get_user", format: "auto" })
// auto — emit compact if savings ≥ 15%, otherwise JSON
// compact — always compact
// json — never compact (back-compat)

Benchmark: 45.5% bytes saved across representative tools, peaks at 55.4% on graph and outline responses.

Encoding savings stack on top of retrieval savings — every byte off the wire is a byte the agent doesn't pay to read.

Why LoomMCP is Better

1. Higher Token Reduction

2. Free Forever

No enterprise sales calls. No license management. Install and forget.

3. GPU-Native Architecture

• @xenova/transformers — Real CUDA semantic search
• ONNX runtime for CPU fallback
• No external API dependencies
• Your data stays local

4. SQLite Workspace

• Persistent symbol storage
• Cross-session memory
• Query-able metrics database

5. Live Watching

• Auto-reindex on file changes
• Debounce support
• Event-driven updates

Real-world results

Reproducible token efficiency benchmark

Average: 97.75% token reduction

Run: npm run build && node eval/benchmark.js .

vs Native Tools

What You Get

Symbol-level retrieval

Find and fetch functions, classes, methods, constants, and more without opening entire files.

Faster repo understanding

Inspect repository structure and file outlines before asking for source.

Lower token spend

Send the model the code it needs, not 1,500 lines of collateral damage.

Structural queries native tools can't answer

• loom_find_importers — tells you what imports a file
• loom_blast_radius — tells you what breaks if you change a symbol, with depth-weighted risk scores and source snippets
• loom_get_class_hierarchy — traverses inheritance chains
• loom_find_dead_code — finds symbols and files unreachable from any entry point
• loom_get_hotspots — surfaces the riskiest code by combining complexity with git churn
• loom_get_dependency_cycles — detects circular imports
• loom_pagerank_centrality — ranks your codebase by architectural centrality

These are not "faster grep" — they are questions grep cannot answer at all.

Agent config hygiene

loom_audit_agent_config scans your CLAUDE.md, .cursorrules, and other agent config files for:

• Per-file token cost
• Stale symbol references (cross-referenced against the index — catches renamed or deleted functions)
• Dead file paths
• Redundancy between configs
• Bloat and scope leaks

Symbol provenance

loom_get_symbol_provenance is git archaeology:

• Given a symbol, traces every commit that touched it
• Classifies each commit (creation, bugfix, refactor, feature, perf, rename, revert)
• Generates a human-readable narrative explaining who created it, why, and how it evolved

Refactoring Planner

loom_plan_refactoring generates exact edit-ready instructions for rename, move, and extract operations. Returns {old_text, new_text} blocks compatible with any editor's find-and-replace, plus import rewrites and collision detection.

Token-Budgeted Context

loom_get_ranked_context assembles context within a token budget — stops when full, not when too much.

Why agents need this

Most agents still inspect codebases like tourists trapped in an airport gift shop:

• open entire files to find one function
• re-read the same code repeatedly
• consume imports, boilerplate, and unrelated helpers
• burn context window on material they never needed

LoomMCP fixes that:

• search symbols by name, kind, or language — with fuzzy matching and semantic search
• inspect file and repo outlines before pulling source
• retrieve exact implementations only
• grab token-budgeted context for a task
• fall back to text search when structure alone isn't enough
• detect dead code, trace impact, rank by centrality, and map git diffs to symbols

Agents do not need bigger and bigger context windows.

They need better aim.

Supported Languages (15+)

Quick Start

# Install
npm install @loom-mcp/server

# Build
npm run build

# Start (stdio mode)
npm start

# Or start dashboard
LOOM_DASHBOARD_PORT=2337 npm start

Add to Claude Code

claude mcp add loom npm @loom-mcp/server

Or use npx

claude mcp add loom npx @loom-mcp/server

Live Dashboard

LoomMCP ships with a full observability dashboard at http://localhost:2337 — no extra setup required.

The dashboard tracks every tool call, accumulates token savings across sessions, and gives you real-time visibility into what Claude is doing with your codebase.

What it shows

Dashboard pages

Get Topology — Shows the last AST skeleton Claude fetched. TOON output with file count, token estimate, and language breakdown.

Active Lens — Detailed view of focused files with lines, tokens, dependencies, and focus timestamps.

Settings — Configure workspace root, max depth, focus budget, auto-refresh, and theme. Reads from /api/settings.

Real-world example: fixing an auth bug

Here's what happens in the dashboard when Claude diagnoses a login bug in a 40,000-token TypeScript codebase:

Step 1 — loom_get_topology("src/")
  → 16 files scanned, 54,932 raw tokens → 1,456 TOON tokens (97% reduction)
  → Dashboard: Files Indexed +16, Tokens Saved +53,476

Step 2 — loom_focus("src/auth.ts::loginUser")
  → 42 lines paged in (1,204 tokens). Rest of auth.ts stays out of context.
  → Dashboard: Active Lens 1/20, Focus Budget 5%

Step 3 — loom_search_refs("loginUser")
  → 14 call sites found across 8 files in 44ms
  → Dashboard: Events feed records loom_search_refs · 44ms

Step 4 — loom_get_active_diff()
  → Diff scoped to changed symbols only
  → Dashboard: Total session savings 40,616 tokens (66%)

Accessing the dashboard

The dashboard starts automatically when LoomMCP runs:

# Start MCP server (dashboard starts at :2337 automatically)
node dist/index.js

# Or via npm
npm start

Open http://localhost:2337 in your browser.

The dashboard is a static Next.js app served directly by the MCP server — no separate process needed. Token savings persist to .loom/savings.json between restarts.

Dashboard API endpoints

Tools (40+)

Indexing

• loom_get_topology — Skeletonize codebase
• loom_index_folder — Index local folder
• loom_list_repos — List indexed repos

Search

• loom_search_symbols — Symbol search
• loom_bm25_search — BM25 ranking
• loom_fuzzy_search — Fuzzy matching
• loom_search_text — Full-text search
• loom_semantic_search — GPU embeddings

Retrieval

• loom_get_symbol — Exact source
• loom_get_ranked_context — Token-budgeted context
• loom_focus — Page in full implementation

Analysis

• loom_find_importers — Reverse dependencies
• loom_blast_radius — Change impact
• loom_find_dead_code — Unused code
• loom_get_class_hierarchy — Inheritance
• loom_pagerank_centrality — Importance
• loom_get_hotspots — Risk areas
• loom_get_changed_symbols — Git diff mapping
• loom_get_dependency_cycles — Circular imports

Workflow

• loom_remember — Cross-session memory
• loom_watch_start/stop — Live watching
• loom_audit_agent_config — Config hygiene
• loom_plan_refactoring — Refactor planning

Observability

• loom_get_metrics — Session stats
• loom_get_deps — Dependency graph
• loom_workspace_stats — SQLite stats

vs jCodeMunch

Contributing

See CONTRIBUTING.md for development setup.

License

MIT — Free forever, no enterprise sales calls.

Star Us

Help us compete with jCodeMunch (1.9k stars):

# If you believe in this project, share it!

Stop paying your model to read the whole damn file.

LoomMCP turns repo exploration into structured retrieval.