llm-tldr 1.0.0

Token-efficient code analysis for LLMs. 5-layer stack: AST, Call Graph, CFG, DFG, PDG. 95% token savings. 15 languages.

LLM-TLDR: Code Analysis That Fits In Context

95% token savings. 155x faster queries. 16 languages.

LLMs can't read your entire codebase. TLDR extracts structure, traces dependencies, and gives them exactly what they need.

pip install llm-tldr

---

Table of Contents

Quick Start

• 30 Second Setup
• Basic Commands

For Developers

• All Commands
• MCP Integration
• Daemon Mode

For AI Agents

• What This Tool Does
• When To Use Each Command
• Full Documentation

---

What This Tool Does

Problem	TLDR Solution
100K line codebase, 200K token limit	Extract structure only → 95% fewer tokens
"Who calls this function?"	tldr impact func → reverse call graph
"What affects line 42?"	tldr slice file func 42 → program slice
grep finds syntax, not behavior	tldr semantic "validate JWT" → finds by meaning
CLI spawns are slow (30s)	Daemon mode → 100ms queries

---

Quick Start

# Install
pip install llm-tldr

# Index your project
tldr warm /path/to/project

# Get LLM-ready context for a function
tldr context main --project /path/to/project

That's it. Daemon auto-starts and keeps indexes in memory.

---

Basic Commands

# See project structure
tldr tree src/

# Get code structure (functions, classes)
tldr structure src/ --lang python

# Search for patterns
tldr search "def process" src/

# Get LLM-ready context
tldr context main --project src/

---

Commands

Code Exploration

Command	Description
tldr tree [path]	File tree
tldr structure [path] --lang <lang>	Code structure (codemaps)
tldr search <pattern> [path]	Search files
tldr extract <file>	Full file analysis
tldr context <entry> --project <path>	LLM-ready context (95% savings)

Flow Analysis

Command	Description
tldr cfg <file> <function>	Control flow graph
tldr dfg <file> <function>	Data flow graph
tldr slice <file> <func> <line>	Program slice (what affects line N?)

Cross-File Analysis

Command	Description
tldr calls [path]	Build call graph
tldr impact <func> [path]	Find all callers (reverse call graph)
tldr dead [path]	Find unreachable code
tldr arch [path]	Detect architectural layers
tldr imports <file>	Parse imports
tldr importers <module> [path]	Find files that import a module

Diagnostics

Command	Description
tldr diagnostics <file>	Type check + lint
tldr change-impact [files]	Find tests affected by changes
tldr doctor	Check/install diagnostic tools

Semantic Search

Command	Description
tldr warm <path>	Build all indexes (including semantic)
tldr semantic <query> [path]	Natural language code search

Daemon

Command	Description
tldr daemon start	Start background daemon
tldr daemon stop	Stop daemon
tldr daemon status	Check daemon status

---

Command Reference

For AI agents reading this file:

Task	Command	Output
Understand a function	tldr context <func> --project .	LLM-ready text with structure, calls, complexity
Before editing a file	tldr extract <file>	Functions, classes, imports
Find who calls X	tldr impact <func> .	List of callers with file:line
Debug "why is X null?"	tldr slice <file> <func> <line>	Only lines that affect that line
Find dead code	tldr dead . --entry main	Unreachable functions
Type check before commit	tldr diagnostics .	Errors and warnings
Find code by behavior	tldr semantic "validate auth tokens" .	Functions that match semantically

---

Supported Languages

Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, C#, Kotlin, Scala, Swift, Lua, Elixir

All use the same commands. Language auto-detected or specify with --lang.

---

Daemon Mode

TLDR runs a per-project daemon for 155x faster queries:

tldr daemon start              # Start (auto-backgrounds)
tldr daemon status             # Check status
tldr daemon stop               # Stop

# Queries auto-start daemon if needed
tldr structure .               # First query starts daemon

• Socket: /tmp/tldr-{hash}.sock
• Auto-shutdown after 5 minutes idle
• Per-project isolation (work on multiple projects)

---

Diagnostics Setup

Check what's installed:

tldr doctor

Install missing tools:

tldr doctor --install python   # pyright + ruff
tldr doctor --install go       # golangci-lint

Language	Type Checker	Linter
Python	pyright	ruff
TypeScript	tsc	-
Go	go vet	golangci-lint
Rust	cargo check	clippy
Java	javac	checkstyle
C/C++	gcc/g++	cppcheck
Swift	swiftc	swiftlint
Kotlin	kotlinc	ktlint
Ruby	-	rubocop
PHP	-	phpstan

---

MCP Integration

TLDR provides an MCP server for AI tools (Claude Desktop, Claude Code, OpenCode).

Setup

tldr-mcp --project /path/to/project

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "/path/to/your/project"]
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    }
  }
}

Available MCP Tools

Tool	Description
tree	File tree structure
structure	Code structure (functions, classes)
search	Pattern search
extract	Full file info
context	LLM-ready context (95% savings)
cfg	Control flow graph
dfg	Data flow graph
slice	Program slice
impact	Find callers
dead	Find dead code
arch	Architecture layers
calls	Build call graph
imports	Parse imports
importers	Reverse import lookup
semantic	Semantic search
diagnostics	Type check + lint
change_impact	Find affected tests
status	Daemon status

---

Performance

Metric	Before	After	Improvement
Query latency	1.5s	10ms	155x faster
Tokens for function context	21K	175	99% savings
Tokens for codebase overview	104K	12K	89% savings

---

Full Documentation

For the complete deep-dive (5-layer architecture, benchmarks, real workflows):

Full Documentation

---

License

Apache 2.0 - See LICENSE file for details.