← roadmap

tldr-swinton

keep priority P1 effort M wave 1

What it does: Token-efficient code reconnaissance for LLMs/agents. Confirmed from code (not the hint): a real static-analysis platform — tree-sitter + Python-AST extraction, CFG/DFG/PDG, program slicing, cross-file call graphs, dead-code and architectural-layer detection — plus hybrid semantic search (FAISS nomic-embed-text-v2-moe 768d OR ColBERT LateOn-Code-edge 48d/token via PLAID, fused with BM25 by RRF, verified in semantic/index.py). Ships as a Claude Code plugin: 6 slash commands, 4 autonomous skills (tldrs-session-start, map-codebase, finding-duplicate-functions, interbench-sync), a PostToolUse:Read hook that auto-injects compact extracts on >300-line files (once per file/session), and an MCP server (bin/launch-mcp.sh) registering 26 tools (extract/structure/context/diff_context/impact/semantic/distill/delegate/cfg/dfg/slice/calls/dead/arch/etc). Token economy is the explicit design center: compact/minimal/multi-turn presets, delta/session mode in .tldrs/state.sqlite3, two-stage knapsack-DP + chunk-summary compression, output caps; documented 48–93% savings. Active: v0.7.19, MIT, fork of llm-tldr.

Rationale: This is one of the most mature, defensible plugins in the roster and directly embodies a #1 SOTA theme: token economics as budget survival (“agents spend ~80% of tokens just finding things”; “map-then-read rather than blind file dumps”). It delivers exactly the map-then-read, surgical-read discipline the 2026 cost literature prescribes, with reproducible benchmarks and genuine compiler-grade analysis (CFG/DFG/PDG/slicing) that competitors lack. The autonomous-skill trigger descriptions are well-scoped progressive-disclosure (only ~100 tokens scanned at session start), matching the “skills beat prompts” consensus, and the PostToolUse hook encodes the “don’t blind-Read large files” discipline deterministically (harness-engineering trend). Maintenance is active and already cost-aware (commit cf31cea trims MCP instructions). This is a keep — the core is best-in-class. The single forward-looking gap (eager MCP tool registration) is real but narrow and the maintainer has already started addressing it; it does not rise to a modernize verdict for an otherwise frontier-aligned plugin.

SOTA gap: Progressive tool disclosure on its own MCP surface. The server registers all 26 tldr-code tools eagerly; the 2026 frontier (RAG-MCP: >50% fewer prompt tokens + 3x selection accuracy; Anthropic Tool Search Tool ~85% reduction; code-execution-with-MCP ~98.7%; Cloudflare Code Mode) has made eager large tool catalogs an anti-pattern. It is ironic that a token-efficiency plugin pays a fixed tool-schema tax to load — exactly the “context rot before the first query” failure. Secondary frontier idea it lacks: executable-grounded verification (the SOTA reflection/ReVeal finding that structured tool/test feedback, not static checks, drives reliable self-correction) — its verify_coherence is static cross-file consistency, not test-grounded.

Redundancy: Moderate, manageable overlap. (1) intermap MCP overlaps heavily on code structure / call graphs / change-impact / pattern detection (intermap has code_structure, impact_analysis, change_impact, detect_patterns, project_registry) — a source doc inside this repo even flags extracting embedding infra to a shared lib. (2) Its BM25 + embedding stack duplicates intersearch (the ecosystem’s shared embedding/search infra) and overlaps interknow/qmd (which explicitly has “no vector embeddings yet”). (3) intercache offers session_diff/session_track that overlaps tldr-swinton’s delta/session token-saving mode. None of these is a merge trigger — tldr-swinton’s static-analysis depth (CFG/DFG/PDG/slicing) is unique — but the embedding backend is a candidate to delegate to intersearch rather than maintain twice.

Actions:

  • Adopt progressive tool disclosure on the MCP server: expose a small static surface (extract/structure/context/diff_context/semantic) plus a tool-search/help entrypoint, and defer the ~20 deep-analysis tools (cfg/dfg/slice/calls/dead/arch/etc) behind lazy discovery — cites RAG-MCP / Tool Search Tool / Code Mode (P1).
  • Add a ‘Code Mode’-style single composable entrypoint so the agent drives tldrs as a CLI API it writes against (the README already documents the CLI decision tree) rather than 26 individual MCP tools — caps schema cost regardless of catalog growth.
  • Delegate the embedding/BM25 backend to intersearch (or share its index) instead of maintaining a parallel FAISS/ColBERT+BM25 stack, per the in-repo note recommending an intersearch-style shared lib; keeps the unique static-analysis layers local.
  • Ground verify_coherence/change-impact in executable signals (run affected tests, surface results) per the SOTA reflection finding that test/executor feedback — not static checks — drives reliable agent self-correction.