LLM Context Tools

Generate compact, semantically-rich code context for LLM consumption with 99%+ faster incremental updates.

⚠️ CRITICAL BEHAVIOR CHANGE REQUIRED

BEFORE using Grep, Bash, or Read for code exploration:

1. •ALWAYS check if .llm-context/ directory exists
2. •IF IT EXISTS, use queries FIRST:
   bash

   llm-context query find-function <name>
   llm-context query calls-to <name>
   llm-context side-effects
   

3. •ONLY use grep/read if queries don't provide needed info

This is NOT optional - queries provide richer context (call graphs, side effects, patterns) that grep cannot match.

What This Skill Does

Transforms raw source code into LLM-optimized context:

• •Function call graphs with side effect detection
• •Multi-level summaries (System → Domain → Module)
• •Incremental updates (only re-analyze changed files)
• •Hash-based change tracking
• •Query interface for instant lookups

Token Efficiency: 74-97% reduction vs reading raw files

When To Use

✅ User asks to "analyze this codebase" ✅ User wants to understand code architecture ✅ User needs help debugging or refactoring ✅ You need efficient context about a large codebase ✅ User wants LLM-friendly code documentation

Quick Start

# Check if tool is available
llm-context version

# If not available, user needs to install
# See setup.md for installation

# Run analysis
llm-context analyze

# Query results
llm-context stats

How It Works

Progressive Disclosure Strategy

Read in this order for maximum token efficiency:

1. •

   L0 (200 tokens) → .llm-context/summaries/L0-system.md

   • •Architecture overview, entry points, statistics
2. •

   L1 (50-100 tokens/domain) → .llm-context/summaries/L1-domains.json

   • •Domain boundaries, module lists
3. •

   L2 (20-50 tokens/module) → .llm-context/summaries/L2-modules.json

   • •File-level exports, entry points
4. •

   Graph (variable) → .llm-context/graph.jsonl

   • •Function details, call relationships, side effects
5. •

   Source (as needed) → Read targeted files only

Never read raw source files first! Use summaries and graph for context.

Common Commands

# Analysis
llm-context analyze              # Auto-detect full/incremental
llm-context check-changes        # Preview what changed

# Queries
llm-context stats                # Show statistics
llm-context entry-points         # Find entry points
llm-context side-effects         # Functions with side effects
llm-context query calls-to func  # Who calls this?
llm-context query trace func     # Call tree

Usage Patterns

Pattern 1: First-Time Codebase Understanding

# 1. Run analysis
llm-context analyze

# 2. Read L0 for overview
cat .llm-context/summaries/L0-system.md

# 3. Get statistics
llm-context stats

# 4. Find entry points
llm-context entry-points

Response template:

I've analyzed the codebase:

[L0 content - architecture, components, entry points]

Statistics: X functions, Y files, Z calls

Would you like me to:
1. Explain a specific domain?
2. Trace a function's call path?
3. Review the architecture?

Pattern 2: After Code Changes

# Incremental analysis (only changed files)
llm-context analyze

# See what changed
cat .llm-context/manifest.json

Response: Highlight new/modified functions and their impact

Pattern 3: Debugging

# Find function
llm-context query find-function buggyFunc

# Trace calls
llm-context query trace buggyFunc

# Check side effects
llm-context side-effects | grep buggy

Response: Explain call path and identify potential issues based on side effects

Detailed Guides

Setup & Installation: See setup.md Usage Examples: See examples.md Command Reference: See reference.md Common Workflows: See workflows.md

Side Effect Types

When analyzing functions, these effects are detected:

• •file_io - Reads/writes files
• •network - HTTP, fetch, API calls
• •database - DB queries, ORM
• •logging - Console, logger
• •dom - Browser DOM manipulation

Graph Format

Each function in graph.jsonl:

{
  "id": "functionName",
  "file": "path/file.js",
  "line": 42,
  "calls": ["foo", "bar"],
  "effects": ["database", "network"]
}

Best Practices

✅ REQUIRED WORKFLOW

When .llm-context/ exists, you MUST:

1. •

   Check for analysis data FIRST:

   bash

   ls .llm-context/  # Verify data exists
   

2. •

   Read progressive disclosure hierarchy:

   • •L0 summary: .llm-context/summaries/L0-system.md
   • •L1 domains: .llm-context/summaries/L1-domains.json
   • •L2 modules: .llm-context/summaries/L2-modules.json
3. •

   Use queries for exploration (NOT grep/bash):

   bash

   # Finding functions
   llm-context query find-function <name>
   
   # Understanding dependencies
   llm-context query calls-to <name>
   llm-context query trace <name>
   
   # Side effect analysis
   llm-context side-effects | grep <keyword>
   

4. •

   Only read source after queries don't provide needed info

5. •

   Run incremental analysis after code changes:

   bash

   llm-context analyze  # 99% faster than full re-analysis
   

❌ ANTI-PATTERNS (DO NOT DO THESE)

These waste tokens and miss critical context:

• •❌ Using grep -r "pattern" when .llm-context/ exists → Use queries instead
• •❌ Using Bash to explore code → Use queries instead
• •❌ Reading raw source files first → Read summaries first
• •❌ Re-reading entire codebase on changes → Use incremental analysis
• •❌ Skipping L0/L1/L2 summaries → Miss architectural overview

Remember: Grep shows text matches. Queries show semantic relationships, call graphs, and side effects.

Token Efficiency

Traditional approach:

• •Read 10 files = 10,000 tokens
• •Missing: call graphs, side effects

LLM-context approach:

• •L0 + L1 + Graph = 500-2,000 tokens
• •Includes: complete context + relationships

Savings: 80-95%

Performance

Initial Analysis

• •100 files: 2-5s
• •1,000 files: 30s-2min
• •10,000 files: 5-15min

Incremental Updates

• •1 file: 30-50ms
• •10 files: 200-500ms
• •50 files: 1-2s

Key: Incremental is 99%+ faster at scale

Troubleshooting

"No manifest found" → Run llm-context analyze first

"Cannot find module" → User needs to install: See setup.md

"Graph is empty" → No JavaScript files found. Check directory.

Success Criteria

This skill is working when:

1. •✅ Analysis completes without errors
2. •✅ .llm-context/ exists with all files
3. •✅ llm-context stats shows functions
4. •✅ You use summaries before reading source
5. •✅ Token usage is 50-95% less than raw reading

Summary

Transform from:

• •❌ Reading thousands of lines token-by-token
• •❌ Missing global context
• •❌ Slow re-analysis

To:

• •✅ Compact semantic representations
• •✅ Call graphs + side effects
• •✅ 99%+ faster incremental updates
• •✅ 50-95% token savings