source-insights - SKILL.md Agent Skill

name: source-insights description: > Clone, index, and search the source code of open-source dependencies your project uses. Use this skill whenever the user needs to debug an integration with a FOSS library, understand how a dependency works internally, trace a bug into dependency source, read the actual implementation of an upstream API, or wants to set up local source indexing for their project's deps. Also trigger when the user says "read the source", "look at the dependency code", "what does actually do", "trace into ", "index my deps", "source insights", or references debugging third-party code. This skill sets up Zoekt (trigram code search from Google/Sourcegraph) + a minimal MCP server to give Claude Code fast, token-efficient access to dependency source without dumping entire repos into context.

Source Insights

Give Claude Code searchable access to the full source of your FOSS dependencies.

Architecture Decision

After evaluating the options, this skill uses Zoekt + a thin MCP wrapper because:

Approach	Strengths	Weaknesses for this use case
Zoekt (this skill)	Local, zero API cost, sub-ms exact search, regex/symbol/file/lang filters, proven at Google/Sourcegraph scale	No semantic search
Vector DB (Milvus, FAISS)	Semantic "how does X work" queries	Requires embeddings API or local GPU, slow indexing, overkill for "find this function"
Context7 MCP	Zero setup, versioned docs	Docs only — no source code, community-curated coverage gaps
GitHub MCP	Can read files via API	Rate limited, no search across files, no offline, burns tokens on full file fetches
LSP via MCP	Jump-to-definition, type info	Heavy per-language setup, no cross-repo search, fragile

Zoekt wins for debugging integrations because you're usually looking for exact things: function signatures, error strings, config keys, type definitions. Trigram indexing finds these in milliseconds across millions of lines. For the "what does this do conceptually" queries, Claude's training data + Context7 docs fill the gap.

Prerequisites

Go 1.21+ (for Zoekt build) OR pre-built Zoekt binaries
Git
Node.js 18+ (for the MCP server, ~60 lines)

Setup

Run scripts/setup.sh to install Zoekt and the MCP server. The script:

Installs Zoekt (go install from source)
Creates ~/.source-insights/ for indexes and cloned repos
Installs the MCP server wrapper
Prints the claude mcp add command to register it

bash /path/to/source-insights/scripts/setup.sh

Usage

1. Resolve and clone deps

From your project root, run the resolver script. It reads your manifest and clones dep sources:

# Auto-detect manifest type
bash /path/to/source-insights/scripts/resolve-deps.sh

# Or specify
bash /path/to/source-insights/scripts/resolve-deps.sh --manifest package.json
bash /path/to/source-insights/scripts/resolve-deps.sh --manifest Cargo.toml
bash /path/to/source-insights/scripts/resolve-deps.sh --manifest pyproject.toml
bash /path/to/source-insights/scripts/resolve-deps.sh --manifest go.mod

Repos clone to ~/.source-insights/repos/<org>/<name>/. Only clones what's missing.

2. Index

bash /path/to/source-insights/scripts/index-deps.sh

Indexes all repos under ~/.source-insights/repos/. Incremental — only re-indexes changed repos.

3. Search via Claude Code

Once the MCP server is registered, Claude Code can use these tools:

search_deps — Search across all indexed dependency source. Supports Zoekt query syntax:
- functionName — basic text search
- sym:createClient — symbol definitions
- file:\.rs$ parse — file type filter
- repo:tokio spawn — specific repo
- lang:python async def — language filter
- "exact phrase" — exact match
- err1 OR err2 — boolean
list_deps — List all indexed dependency repos with stats
read_dep_file — Read a specific file from an indexed dependency (path from search results)

4. Add specific repos manually

bash /path/to/source-insights/scripts/add-repo.sh https://github.com/org/repo
bash /path/to/source-insights/scripts/index-deps.sh

CLAUDE.md Integration

Add to your project's CLAUDE.md:

## Dependency Source

This project uses source-insights for searchable access to dependency source code.
When debugging integration issues, use the `search_deps` MCP tool to find relevant
upstream code before guessing at behavior. Prefer `sym:` queries for definitions
and exact error strings for tracing issues.

Key deps to search when debugging:
- <list your critical deps here>

Combining with Context7

Context7 and source-insights are complementary:

Context7: "How do I use the NextAuth session API?" (docs, examples, guides)
source-insights: "What does getServerSession actually return when the cookie is expired?" (implementation)

Add both MCP servers. In CLAUDE.md, guide Claude on when to use which:

- For API usage and examples: use context7
- For implementation details and debugging: use search_deps

Token Efficiency

Zoekt returns compact grep-style output: file:line: matching_content. A typical search returns 5-20 relevant lines consuming ~200-500 tokens, versus reading a full source file at 2000-10000 tokens. Claude can then selectively read_dep_file only the files that matter.

Updating

# Pull latest for all cloned deps
bash /path/to/source-insights/scripts/update-deps.sh

# Re-index after update
bash /path/to/source-insights/scripts/index-deps.sh

Files in this skill

scripts/setup.sh — One-time Zoekt + MCP server installation
scripts/resolve-deps.sh — Parse manifests → clone dep sources
scripts/index-deps.sh — Index all cloned repos with Zoekt
scripts/add-repo.sh — Manually add a repo
scripts/update-deps.sh — Git pull all cloned deps
scripts/mcp-server.js — Minimal MCP server (~80 lines) wrapping Zoekt
references/zoekt-query-syntax.md — Query syntax reference
references/manifest-parsers.md — Supported manifest formats and parsing details