tldr-code

| 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" |

---

```

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

```

---

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 [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

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 --project

tldr context main --project src/ --depth 3

tldr context UserService.create --project . --lang typescript

```

Flow Analysis

```bash

# Control flow graph (complexity)

tldr cfg

tldr cfg src/processor.py process_data

# Returns: cyclomatic complexity, blocks, branches, loops

# Data flow graph (variable tracking)

tldr dfg

tldr dfg src/processor.py process_data

# Returns: where variables are defined, read, modified

# Program slice (what affects line X)

tldr slice

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 [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

tldr imports src/api.py

tldr imports src/api.ts --lang typescript

# Reverse import lookup (who imports this module?)

tldr importers [path]

tldr importers datetime src/

tldr importers UserService . --lang typescript

```

Quality & Testing

```bash

# Type check + lint

tldr diagnostics

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

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)

```

---

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

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

```

---

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"

}

}

```

---

| 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 | - | - | - | - |

---

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.

---

| 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

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())

```

---

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

---

```

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.