Token-efficient code analysis via 5-layer stack (AST, Call Graph, CFG, DFG, PDG). 95% token savings.
tldr-code follows the SKILL.md standard. Use the install command to add it to your agent stack.
---
name: tldr-code
description: Token-efficient code analysis via 5-layer stack (AST, Call Graph, CFG, DFG, PDG). 95% token savings.
allowed-tools: [Bash]
keywords: [debug, refactor, understand, complexity, "call graph", "data flow", "what calls", "how complex", search, explore, analyze, dead code, architecture, imports]
---
# TLDR-Code: Complete Reference
Token-efficient code analysis. **95% savings** vs raw file reads.
## Quick Reference
| Task | Command |
|------|---------|
| File tree | `tldr tree src/` |
| Code structure | `tldr structure . --lang python` |
| Search code | `tldr search "pattern" .` |
| Call graph | `tldr calls src/` |
| Who calls X? | `tldr impact func_name .` |
| Control flow | `tldr cfg file.py func` |
| Data flow | `tldr dfg file.py func` |
| Program slice | `tldr slice file.py func 42` |
| Dead code | `tldr dead src/` |
| Architecture | `tldr arch src/` |
| Imports | `tldr imports file.py` |
| Who imports X? | `tldr importers module_name .` |
| Affected tests | `tldr change-impact --git` |
| Type check | `tldr diagnostics file.py` |
| Semantic search | `tldr semantic search "auth flow"` |
---
## The 5-Layer Stack
```
Layer 1: AST ~500 tokens Function signatures, imports
Layer 2: Call Graph +440 tokens What calls what (cross-file)
Layer 3: CFG +110 tokens Complexity, branches, loops
Layer 4: DFG +130 tokens Variable definitions/uses
Layer 5: PDG +150 tokens Dependencies, slicing
───────────────────────────────────────────────────────────────
Total: ~1,200 tokens vs 23,000 raw = 95% savings
```
---
## CLI Commands
### Navigation
```bash
# File tree
tldr tree [path]
tldr tree src/ --ext .py .ts # Filter extensions
tldr tree . --show-hidden # Include hidden files
# Code structure (codemaps)
tldr structure [path] --lang python
tldr structure src/ --max 100 # Max files to analyze
```
### Search
```bash
# Text search
tldr search <pattern> [path]
tldr search "def process" src/
tldr search "class.*Error" . --ext .py
tldr search "TODO" . -C 3 # 3 lines context
tldr search "func" . --max 50 # Limit results
# Semantic search (natural language)
tldr semantic search "authentication flow"
tldr semantic search "error handling" --k 10
tldr semantic search "database queries" --expand # Include call graph
```
### File Analysis
```bash
# Full file info
tldr extract <file>
tldr extract src/api.py
tldr extract src/api.py --class UserService # Filter to class
tldr extract src/api.py --function process # Filter to function
tldr extract src/api.py --method UserService.get # Filter to method
# Relevant context (follows call graph)
tldr context <entry> --project <path>
tldr context main --project src/ --depth 3
tldr context UserService.create --project . --lang typescript
```
### Flow Analysis
```bash
# Control flow graph (complexity)
tldr cfg <file> <function>
tldr cfg src/processor.py process_data
# Returns: cyclomatic complexity, blocks, branches, loops
# Data flow graph (variable tracking)
tldr dfg <file> <function>
tldr dfg src/processor.py process_data
# Returns: where variables are defined, read, modified
# Program slice (what affects line X)
tldr slice <file> <function> <line>
tldr slice src/processor.py process_data 42
tldr slice src/processor.py process_data 42 --direction forward
tldr slice src/processor.py process_data 42 --var result
```
### Codebase Analysis
```bash
# Build cross-file call graph
tldr calls [path]
tldr calls src/ --lang python
# Reverse call graph (who calls this function?)
tldr impact <func> [path]
tldr impact process_data src/ --depth 5
tldr impact authenticate . --file auth # Filter by file
# Find dead/unreachable code
tldr dead [path]
tldr dead src/ --entry main cli test_ # Specify entry points
tldr dead . --lang typescript
# Detect architectural layers
tldr arch [path]
tldr arch src/ --lang python
# Returns: entry layer, middle layer, leaf layer, circular deps
```
### Import Analysis
```bash
# Parse imports from file
tldr imports <file>
tldr imports src/api.py
tldr imports src/api.ts --lang typescript
# Reverse import lookup (who imports this module?)
tldr importers <module> [path]
tldr importers datetime src/
tldr importers UserService . --lang typescript
```
### Quality & Testing
```bash
# Type check + lint
tldr diagnostics <file|path>
tldr diagnostics src/api.py
tldr diagnostics . --project # Whole project
tldr diagnostics src/ --no-lint # Type check only
tldr diagnostics src/ --format text # Human-readable
# Find affected tests
tldr change-impact [files...]
tldr change-impact # Auto-detect (session/git)
tldr change-impact src/api.py # Explicit files
tldr change-impact --session # Session-modified files
tldr change-impact --git # Git diff files
tldr change-impact --git --git-base main # Diff against branch
tldr change-impact --run # Actually run affected tests
```
### Caching
```bash
# Pre-build call graph cache
tldr warm <path>
tldr warm src/ --lang python
tldr warm . --background # Build in background
# Build semantic index (one-time)
tldr semantic index [path]
tldr semantic index . --lang python
tldr semantic index . --model all-MiniLM-L6-v2 # Smaller model (80MB)
```
---
## Daemon (Faster Queries)
The daemon holds indexes in memory for instant repeated queries.
### Daemon Commands
```bash
# Start daemon (backgrounds automatically)
tldr daemon start
tldr daemon start --project /path/to/project
# Check status
tldr daemon status
# Stop daemon
tldr daemon stop
# Send raw command
tldr daemon query ping
tldr daemon query status
# Notify file change (for hooks)
tldr daemon notify <file>
tldr daemon notify src/api.py
```
### Daemon Features
| Feature | Description |
|---------|-------------|
| Auto-shutdown | 30 minutes idle |
| Query caching | SalsaDB memoization |
| Content hashing | Skip unchanged files |
| Dirty tracking | Incremental re-indexing |
| Cross-platform | Unix sockets / Windows TCP |
### Daemon Socket Protocol
Send JSON to socket, receive JSON response:
```json
// Request
{"cmd": "search", "pattern": "process", "max_results": 10}
// Response
{"status": "ok", "results": [...]}
```
**All 22 daemon commands:**
```
ping, status, shutdown, search, extract, impact, dead, arch,
cfg, dfg, slice, calls, warm, semantic, tree, structure,
context, imports, importers, notify, diagnostics, change_impact
```
---
## Semantic Search (P6)
Natural language code search using embeddings.
### Setup
```bash
# Build index (downloads model on first run)
tldr semantic index .
# Default model: bge-large-en-v1.5 (1.3GB, best quality)
# Smaller model: all-MiniLM-L6-v2 (80MB, faster)
tldr semantic index . --model all-MiniLM-L6-v2
```
### Search
```bash
tldr semantic search "authentication flow"
tldr semantic search "error handling patterns" --k 10
tldr semantic search "database connection" --expand # Follow call graph
```
### Configuration
In `.claude/settings.json`:
```json
{
"semantic_search": {
"enabled": true,
"auto_reindex_threshold": 20,
"model": "bge-large-en-v1.5"
}
}
```
---
## Languages Supported
| Language | AST | Call Graph | CFG | DFG | PDG |
|----------|-----|------------|-----|-----|-----|
| Python | Yes | Yes | Yes | Yes | Yes |
| TypeScript | Yes | Yes | Yes | Yes | Yes |
| JavaScript | Yes | Yes | Yes | Yes | Yes |
| Go | Yes | Yes | Yes | Yes | Yes |
| Rust | Yes | Yes | Yes | Yes | Yes |
| Java | Yes | Yes | - | - | - |
| C/C++ | Yes | Yes | - | - | - |
| Ruby | Yes | - | - | - | - |
| PHP | Yes | - | - | - | - |
| Kotlin | Yes | - | - | - | - |
| Swift | Yes | - | - | - | - |
| C# | Yes | - | - | - | - |
| Scala | Yes | - | - | - | - |
| Lua | Yes | - | - | - | - |
| Elixir | Yes | - | - | - | - |
---
## Ignore Patterns
TLDR respects `.tldrignore` (gitignore syntax):
```gitignore
# .tldrignore
.venv/
__pycache__/
node_modules/
*.min.js
dist/
```
First run creates `.tldrignore` with sensible defaults.
Use `--no-ignore` to bypass.
---
## When to Use TLDR vs Other Tools
| Task | Use TLDR | Use Grep |
|------|----------|----------|
| Find function definition | `tldr extract file --function X` | - |
| Search code patterns | `tldr search "pattern"` | - |
| String literal search | - | `grep "literal"` |
| Config values | - | `grep "KEY="` |
| Cross-file calls | `tldr calls` | - |
| Reverse deps | `tldr impact func` | - |
| Complexity analysis | `tldr cfg file func` | - |
| Variable tracking | `tldr dfg file func` | - |
| Natural language query | `tldr semantic search` | - |
---
## Python API
```python
from tldr.api import (
# L1: AST
extract_file, extract_functions, get_imports,
# L2: Call Graph
build_project_call_graph, get_intra_file_calls,
# L3: CFG
get_cfg_context,
# L4: DFG
get_dfg_context,
# L5: PDG
get_slice, get_pdg_context,
# Unified
get_relevant_context,
# Analysis
analyze_dead_code, analyze_architecture, analyze_impact,
)
# Example: Get context for LLM
ctx = get_relevant_context("src/", "main", depth=2, language="python")
print(ctx.to_llm_string())
```
---
## Bug Fixing Workflow (Navigation + Read)
**Key insight:** TLDR navigates, then you read. Don't try to fix bugs from summaries alone.
### The Pattern
```bash
# 1. NAVIGATE: Find which files matter
tldr imports file.py # What does buggy file depend on?
tldr impact func_name . # Who calls the buggy function?
tldr calls . # Cross-file edges (follow 2-hop for models)
# 2. READ: Get actual code for critical files (2-4 files, not all 50)
# Use Read tool or tldr search -C for code with context
tldr search "def buggy_func" . -C 20
```
### Why This Works
For cross-file bugs (e.g., wrong field name, type mismatch), you need to see:
- The file with the bug (handler accessing `task.user_id`)
- The file with the contract (model defining `owner_id`)
TLDR finds which files matter. Then you read them.
### Getting More Context
If TLDR output isn't enough:
- `tldr search "pattern" . -C 20` - Get actual code with 20 lines context
- `tldr imports file.py` - See what a file depends on
- Read the file directly if you need the full implementation
---
## Token Savings Evidence
```
Raw file read: 23,314 tokens
TLDR all layers: 1,189 tokens
─────────────────────────────────
Savings: 95%
```
The insight: Call graph navigates to relevant code, then layers give structured summaries. You don't read irrelevant code.