TLDR: automatic code summaries + a CLI for deliberate lookups

If the checkout you're working in has .venv/bin/tldr, TLDR summarizes code
files into ~500–1,200 tokens instead of the 10–25k a full Read would consume.

How it actually reaches you (PAN-3534): a PreToolUse hook on Read. When
you Read a large code file, the hook substitutes a structured summary
automatically — you don't invoke anything. There are no tldr_* MCP tools
in agent sessions; older docs that told you to call tldr_context /
tldr_semantic as tools described a surface that was never wired up. Do not
wait for or request those tools.

The workflow

1. Just Read. Large code files come back as TLDR summaries automatically
   when a local venv exists. Treat the summary as the answer to structure
   questions.
2. Read full content only when editing. Use Read with offset/limit
   for the specific range you'll touch — targeted reads always bypass the
   hook. Recently-edited files also bypass, so you can verify your own changes.
3. Deliberate lookups via the CLI (Bash, from the checkout root):
   • .venv/bin/tldr context <module-path> --lang <lang> — exports, imports,
     key function shapes (module path without extension, e.g.
     src/lib/agents).
   • .venv/bin/tldr extract <file> — structured JSON (functions, classes,
     params) for an exact file path.
   • .venv/bin/tldr structure <directory> — orient in an unfamiliar module.

Scope rules

• The hook only serves files from the checkout that owns the venv. Files in a
  workspace without its own .venv get normal full Reads — that's expected,
  not breakage.
• Config/data files (JSON, TOML, .env), markdown, and small files (<3KB) are
  never intercepted — just Read them.

Observability

• <checkout>/.tldr/interceptions.log — each summary served
  (timestamp file_size rel_path).
• <checkout>/.tldr/bypasses.log — deliberate bypasses with reasons
  (recently-edited, sparse-content, binary-fail, no-content,
  no-venv).
• <checkout>/.tldr/failures.log — broken-binary diagnostics.

Troubleshooting

• No summaries appearing? Check the checkout has .venv/bin/tldr and that
  agents.tldr.enabled isn't false (OVERDECK_TLDR_ENABLED=0 also disables).
• Index stale? The post-edit hook re-warms after 10 edits (deduped by
  .tldr/warm.lock); Cloister also warms on workspace create and after merge.
  For one specific fresh file, just Read it with offset/limit.

See also

• pan admin tldr status — operator view of running daemons. Use the
  pan-admin-tldr skill for daemon lifecycle.