tldr-swinton

tldrs

Token-efficient code analysis platform for LLMs and AI agents.

33 commands. 5 analysis layers. 13+ languages. 48–93% token savings.

Why tldrs?

For Humans	For AI Agents	For Both
Explore unfamiliar codebases fast	Structured context that fits in a prompt	Semantic search by meaning, not text
Understand call chains and data flow	Token budgets to control cost	Diff-focused context for recent changes
Find dead code and architectural layers	Session tracking for multi-turn work	5-layer analysis: AST → Call Graph → CFG → DFG → PDG

tldrs isn't just extraction: it's full static analysis (control flow, data flow, program slicing), semantic search (embeddings + BM25 hybrid), and session-aware artifact storage, all designed to produce the smallest context an LLM needs to do its job.

Quick start

Install

# One-liner (recommended)
curl -fsSL https://raw.githubusercontent.com/mistakeknot/tldr-swinton/main/scripts/install.sh | bash

# Or via uv
uv pip install tldr-swinton

# Or manual
git clone https://github.com/mistakeknot/tldr-swinton
cd tldr-swinton && uv sync --extra semantic-ollama

Try it

tldrs structure src/              # Code structure (functions, classes, imports)
tldrs diff-context --project .    # Context pack for your recent changes
tldrs index . && tldrs find "authentication logic"   # Semantic search
tldrs context main --project .    # Call-graph context around a symbol

Verify

tldrs --version   # 0.7.0
tldrs doctor      # Check optional tools (type checkers, linters)

Commands

All 33 top-level commands grouped by use case. Each command supports --help for full options.

Reconnaissance

Get oriented in a codebase or understand recent changes.

Command	Description
diff-context	Diff-focused context pack (merge-base → HEAD)
context	Call-graph context around a symbol (--depth, --budget, --format)
find	Semantic code search (requires tldrs index first)
structural	Structural search using ast-grep patterns
search	Regex pattern search across files
quickstart	Quick reference guide for AI agents

Structure & extraction

Understand file and project organization.

Command	Description
structure	Code structure: functions, classes, imports (codemaps)
extract	Full file analysis as JSON
tree	File tree
imports	Parse imports from a source file
importers	Reverse import lookup: find all files importing a module

Deep analysis

Static analysis beyond surface-level extraction.

Command	Description
cfg	Control flow graph for a function
dfg	Data flow graph for a function
slice	Program slice: what affects a specific line
calls	Cross-file call graph
impact	Reverse call graph: find all callers of a function
dead	Find unreachable (dead) code
arch	Detect architectural layers from call patterns
change-impact	Find tests affected by changed files
diagnostics	Type checker and linter diagnostics
distill	Compress context for sub-agent consumption
hotspots	Most frequently used symbols across sessions

Semantic search

Embedding-based search: find code by meaning, not keywords.

Command	Description
index	Build or update the semantic index (--backend ollama|sentence-transformers|auto)
find	Query the index (e.g., tldrs find "error handling patterns")
semantic	Low-level semantic search subcommands

Infrastructure

Daemon, caching, and health checks.

Command	Description
daemon	Daemon management (start, stop, status)
warm	Pre-build call graph cache for faster queries
prebuild	Precompute context bundle for current HEAD
doctor	Check and install diagnostic tools
presets	List flag presets and their expansions
manifest	Machine-readable JSON of all tldrs capabilities

Artifact storage

Persistent storage for agent workflows.

Command	Description	Subcommands
vhs	Content-addressed store for tool outputs	9 (put, get, cat, has, info, rm, ls, stats, gc)
wb	Agent workbench: capsules, decisions, hypotheses	18 (capture, show, decide, hypothesis, link, ...)
bench	Benchmarking harness for agent improvements	4 (run, list, report, compare)

Agent integration

Claude code plugin

/plugin marketplace add mistakeknot/interagency-marketplace
/plugin install tldr-swinton