{"id":50721018,"url":"https://github.com/parcadei/llm-tldr","last_synced_at":"2026-06-20T05:03:36.185Z","repository":{"id":331548269,"uuid":"1130952278","full_name":"parcadei/llm-tldr","owner":"parcadei","description":"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.","archived":false,"fork":false,"pushed_at":"2026-01-10T16:54:16.000Z","size":372,"stargazers_count":96,"open_issues_count":4,"forks_count":17,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-11T00:11:24.460Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parcadei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T08:55:54.000Z","updated_at":"2026-01-10T23:37:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parcadei/llm-tldr","commit_stats":null,"previous_names":["parcadei/llm-tldr"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/parcadei/llm-tldr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fllm-tldr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fllm-tldr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fllm-tldr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fllm-tldr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parcadei","download_url":"https://codeload.github.com/parcadei/llm-tldr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fllm-tldr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34557553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T00:00:33.540Z","updated_at":"2026-06-20T05:03:36.180Z","avatar_url":"https://github.com/parcadei.png","language":"Python","funding_links":[],"categories":["AI"],"sub_categories":[],"readme":"# TLDR: Code Analysis for AI Agents\n\n[![PyPI](https://img.shields.io/pypi/v/llm-tldr)](https://pypi.org/project/llm-tldr/)\n[![Python](https://img.shields.io/pypi/pyversions/llm-tldr)](https://pypi.org/project/llm-tldr/)\n[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)\n\n**Give LLMs exactly the code they need. Nothing more.**\n\n```bash\n# One-liner: Install, index, search\npip install llm-tldr \u0026\u0026 tldr warm . \u0026\u0026 tldr semantic \"what you're looking for\" .\n```\n\nYour codebase is 100K lines. Claude's context window is 200K tokens. Raw code won't fit—and even if it did, the LLM would drown in irrelevant details.\n\nTLDR extracts *structure* instead of dumping *text*. The result: **95% fewer tokens** while preserving everything needed to understand and edit code correctly.\n\n```bash\npip install llm-tldr\ntldr warm .                    # Index your project\ntldr context main --project .  # Get LLM-ready summary\n```\n\n---\n\n## How It Works\n\nTLDR builds 5 analysis layers, each answering different questions:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Layer 5: Program Dependence  → \"What affects line 42?\"      │\n│ Layer 4: Data Flow           → \"Where does this value go?\"  │\n│ Layer 3: Control Flow        → \"How complex is this?\"       │\n│ Layer 2: Call Graph          → \"Who calls this function?\"   │\n│ Layer 1: AST                 → \"What functions exist?\"      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**Why layers?** Different tasks need different depth:\n- Browsing code? Layer 1 (structure) is enough\n- Refactoring? Layer 2 (call graph) shows what breaks\n- Debugging null? Layer 5 (slice) shows only relevant lines\n\nThe daemon keeps indexes in memory for **100ms queries** instead of 30-second CLI spawns.\n\n### Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                         YOUR CODE                                │\n│  src/*.py, lib/*.ts, pkg/*.go                                    │\n└───────────────────────────┬──────────────────────────────────────┘\n                            │ tree-sitter\n                            ▼\n┌──────────────────────────────────────────────────────────────────┐\n│                     5-LAYER ANALYSIS                             │\n│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐     │\n│  │   AST   │→│  Calls  │→│   CFG   │→│   DFG   │→│   PDG   │     │\n│  │   L1    │ │   L2    │ │   L3    │ │   L4    │ │   L5    │     │\n│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘     │\n└───────────────────────────┬──────────────────────────────────────┘\n                            │ bge-large-en-v1.5\n                            ▼\n┌──────────────────────────────────────────────────────────────────┐\n│                    SEMANTIC INDEX                                │\n│  1024-dim embeddings in FAISS  →  \"find JWT validation\"          │\n└───────────────────────────┬──────────────────────────────────────┘\n                            │\n                            ▼\n┌──────────────────────────────────────────────────────────────────┐\n│                       DAEMON                                     │\n│  In-memory indexes  •  100ms queries  •  Auto-lifecycle          │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### The Semantic Layer: Search by Behavior\n\nThe real power comes from combining all 5 layers into **searchable embeddings**.\n\nEvery function gets indexed with:\n- Signature + docstring (L1)\n- What it calls + who calls it (L2)\n- Complexity metrics (L3)\n- Data flow patterns (L4)\n- Dependencies (L5)\n- First ~10 lines of actual code\n\nThis gets encoded into **1024-dimensional vectors** using `bge-large-en-v1.5`. The result: search by *what code does*, not just what it says.\n\n```bash\n# \"validate JWT\" finds verify_access_token() even without that exact text\ntldr semantic \"validate JWT tokens and check expiration\" .\n```\n\n**Why this works:** Traditional search finds `authentication` in variable names and comments. Semantic search understands that `verify_access_token()` *performs* JWT validation because the call graph and data flow reveal its purpose.\n\n### Setting Up Semantic Search\n\n```bash\n# Build the semantic index (one-time, ~2 min for typical project)\ntldr warm /path/to/project\n\n# Search by behavior\ntldr semantic \"database connection pooling\" .\n```\n\nEmbedding dependencies (`sentence-transformers`, `faiss-cpu`) are included with `pip install llm-tldr`. The index is cached in `.tldr/cache/semantic.faiss`.\n\n### Keeping the Index Fresh\n\nThe daemon tracks dirty files and auto-rebuilds after 20 changes, but you need to notify it when files change:\n\n```bash\n# Notify daemon of a changed file\ntldr daemon notify src/auth.py --project .\n```\n\n**Integration options:**\n\n1. **Git hook** (post-commit):\n   ```bash\n   git diff --name-only HEAD~1 | xargs -I{} tldr daemon notify {} --project .\n   ```\n\n2. **Editor hook** (on save):\n   ```bash\n   tldr daemon notify \"$FILE\" --project .\n   ```\n\n3. **Manual rebuild** (when needed):\n   ```bash\n   tldr warm .  # Full rebuild\n   ```\n\nThe daemon auto-rebuilds semantic embeddings in the background once the dirty threshold (default: 20 files) is reached.\n\n---\n\n## The Workflow\n\n### Before Reading Code\n```bash\ntldr tree src/                      # See file structure\ntldr structure src/ --lang python   # See functions/classes\n```\n\n### Before Editing\n```bash\ntldr extract src/auth.py            # Full file analysis\ntldr context login --project .      # LLM-ready summary (95% savings)\n```\n\n### Before Refactoring\n```bash\ntldr impact login .                 # Who calls this? (reverse call graph)\ntldr change-impact                  # Which tests need to run?\n```\n\n### Debugging\n```bash\ntldr slice src/auth.py login 42     # What affects line 42?\ntldr dfg src/auth.py login          # Trace data flow\n```\n\n### Finding Code by Behavior\n```bash\ntldr semantic \"validate JWT tokens\" .   # Natural language search\n```\n\n---\n\n## Quick Setup\n\n### 1. Install\n\n```bash\npip install llm-tldr\n```\n\n### 2. Index Your Project\n\n```bash\ntldr warm /path/to/project\n```\n\nThis builds all analysis layers and starts the daemon. Takes 30-60 seconds for a typical project, then queries are instant.\n\n### 3. Start Using\n\n```bash\ntldr context main --project .   # Get context for a function\ntldr impact helper_func .       # See who calls it\ntldr semantic \"error handling\"  # Find by behavior\n```\n\n---\n\n## Real Example: Why This Matters\n\n**Scenario:** Debug why `user` is null on line 42.\n\n**Without TLDR:**\n1. Read the 150-line function\n2. Trace every variable manually\n3. Miss the bug because it's hidden in control flow\n\n**With TLDR:**\n```bash\ntldr slice src/auth.py login 42\n```\n\n**Output:** Only 6 lines that affect line 42:\n```python\n3:   user = db.get_user(username)\n7:   if user is None:\n12:      raise NotFound\n28:  token = create_token(user)  # ← BUG: skipped null check\n35:  session.token = token\n42:  return session\n```\n\nThe bug is obvious. Line 28 uses `user` without going through the null check path.\n\n---\n\n## Command Reference\n\n### Exploration\n| Command | What It Does |\n|---------|--------------|\n| `tldr tree [path]` | File tree |\n| `tldr structure [path] --lang \u003clang\u003e` | Functions, classes, methods |\n| `tldr search \u003cpattern\u003e [path]` | Text pattern search |\n| `tldr extract \u003cfile\u003e` | Full file analysis |\n\n### Analysis\n| Command | What It Does |\n|---------|--------------|\n| `tldr context \u003cfunc\u003e --project \u003cpath\u003e` | LLM-ready summary (95% savings) |\n| `tldr cfg \u003cfile\u003e \u003cfunction\u003e` | Control flow graph |\n| `tldr dfg \u003cfile\u003e \u003cfunction\u003e` | Data flow graph |\n| `tldr slice \u003cfile\u003e \u003cfunc\u003e \u003cline\u003e` | Program slice |\n\n### Cross-File\n| Command | What It Does |\n|---------|--------------|\n| `tldr calls [path]` | Build call graph |\n| `tldr impact \u003cfunc\u003e [path]` | Find all callers (reverse call graph) |\n| `tldr dead [path]` | Find unreachable code |\n| `tldr arch [path]` | Detect architecture layers |\n| `tldr imports \u003cfile\u003e` | Parse imports |\n| `tldr importers \u003cmodule\u003e [path]` | Find files that import a module |\n\n### Semantic\n| Command | What It Does |\n|---------|--------------|\n| `tldr warm \u003cpath\u003e` | Build all indexes (including embeddings) |\n| `tldr semantic \u003cquery\u003e [path]` | Natural language code search |\n\n### Diagnostics\n| Command | What It Does |\n|---------|--------------|\n| `tldr diagnostics \u003cfile\u003e` | Type check + lint |\n| `tldr change-impact [files]` | Find tests affected by changes |\n| `tldr doctor` | Check/install diagnostic tools |\n\n### Daemon\n| Command | What It Does |\n|---------|--------------|\n| `tldr daemon start` | Start background daemon |\n| `tldr daemon stop` | Stop daemon |\n| `tldr daemon status` | Check status |\n\n---\n\n## Supported Languages\n\nPython, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, C#, Kotlin, Scala, Swift, Lua, Elixir\n\nLanguage is auto-detected or specify with `--lang`.\n\n---\n\n## MCP Integration\n\nFor AI tools (Claude Desktop, Claude Code):\n\n**Claude Desktop** - Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"tldr\": {\n      \"command\": \"tldr-mcp\",\n      \"args\": [\"--project\", \"/path/to/your/project\"]\n    }\n  }\n}\n```\n\n**Claude Code** - Add to `.claude/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"tldr\": {\n      \"command\": \"tldr-mcp\",\n      \"args\": [\"--project\", \".\"]\n    }\n  }\n}\n```\n\n---\n\n## Configuration\n\n### `.tldrignore` - Exclude Files\n\nTLDR respects `.tldrignore` (gitignore syntax) for all commands including `tree`, `structure`, `search`, `calls`, and semantic indexing:\n\n```bash\n# Auto-create with sensible defaults\ntldr warm .  # Creates .tldrignore if missing\n```\n\n**Default exclusions:**\n- `node_modules/`, `.venv/`, `__pycache__/`\n- `dist/`, `build/`, `*.egg-info/`\n- Binary files (`*.so`, `*.dll`, `*.whl`)\n- Security files (`.env`, `*.pem`, `*.key`)\n\n**Customize** by editing `.tldrignore`:\n```gitignore\n# Add your patterns\nlarge_test_fixtures/\nvendor/\ndata/*.csv\n```\n\n**CLI Flags:**\n```bash\n# Add patterns from command line (can be repeated)\ntldr --ignore \"packages/old/\" --ignore \"*.generated.ts\" tree .\n\n# Bypass all ignore patterns\ntldr --no-ignore tree .\n```\n\n### Settings - Daemon Behavior\n\nCreate `.tldr/config.json` for daemon settings:\n\n```json\n{\n  \"semantic\": {\n    \"enabled\": true,\n    \"auto_reindex_threshold\": 20\n  }\n}\n```\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `enabled` | `true` | Enable semantic search |\n| `auto_reindex_threshold` | `20` | Files changed before auto-rebuild |\n\n### Monorepo Support\n\nFor monorepos, create `.claude/workspace.json` to scope indexing:\n\n```json\n{\n  \"active_packages\": [\"packages/core\", \"packages/api\"],\n  \"exclude_patterns\": [\"**/fixtures/**\"]\n}\n```\n\n---\n\n## Performance\n\n| Metric | Raw Code | TLDR | Improvement |\n|--------|----------|------|-------------|\n| Tokens for function context | 21,000 | 175 | **99% savings** |\n| Tokens for codebase overview | 104,000 | 12,000 | **89% savings** |\n| Query latency (daemon) | 30s | 100ms | **300x faster** |\n\n---\n\n## Deep Dive\n\nFor the full architecture explanation, benchmarks, and advanced workflows:\n\n**[Full Documentation](./docs/TLDR.md)**\n\n---\n\n## License\n\nAGPL-3.0 - See LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcadei%2Fllm-tldr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparcadei%2Fllm-tldr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcadei%2Fllm-tldr/lists"}