tldr-code

TLDR-Code：完全リファレンス

トークン効率に優れたコード分析です。ファイルをそのまま読み込む場合と比べて、95%削減できます。

クイックリファレンス

タスク	コマンド
ファイルツリー	tldr tree src/
コード構造	tldr structure . --lang python
コード検索	tldr search "pattern" .
呼び出しグラフ	tldr calls src/
X を呼び出しているもの	tldr impact func_name .
制御フロー	tldr cfg file.py func
データフロー	tldr dfg file.py func
プログラムスライス	tldr slice file.py func 42
デッドコード	tldr dead src/
アーキテクチャ	tldr arch src/
インポート	tldr imports file.py
X をインポートしているもの	tldr importers module_name .
影響を受けるテスト	tldr change-impact --git
型チェック	tldr diagnostics file.py
セマンティック検索	tldr semantic search "auth flow"

---

5 層スタック

Layer 1: AST         ~500 tokens   Function signatures, imports
Layer 2: Call Graph  +440 tokens   What calls what (cross-file)
Layer 3: CFG         +110 tokens   Complexity, branches, loops
Layer 4: DFG         +130 tokens   Variable definitions/uses
Layer 5: PDG         +150 tokens   Dependencies, slicing
───────────────────────────────────────────────────────────────
Total:              ~1,200 tokens  vs 23,000 raw = 95% savings

---

CLI コマンド

ナビゲーション

# File tree
tldr tree [path]
tldr tree src/ --ext .py .ts        # Filter extensions
tldr tree . --show-hidden           # Include hidden files

# Code structure (codemaps)
tldr structure [path] --lang python
tldr structure src/ --max 100       # Max files to analyze

検索

# Text search
tldr search <pattern> [path]
tldr search "def process" src/
tldr search "class.*Error" . --ext .py
tldr search "TODO" . -C 3           # 3 lines context
tldr search "func" . --max 50       # Limit results

# Semantic search (natural language)
tldr semantic search "authentication flow"
tldr semantic search "error handling" --k 10
tldr semantic search "database queries" --expand  # Include call graph

ファイル分析

# Full file info
tldr extract <file>
tldr extract src/api.py
tldr extract src/api.py --class UserService      # Filter to class
tldr extract src/api.py --function process       # Filter to function
tldr extract src/api.py --method UserService.get # Filter to method

# Relevant context (follows call graph)
tldr context <entry> --project <path>
tldr context main --project src/ --depth 3
tldr context UserService.create --project . --lang typescript

フロー分析

# Control flow graph (complexity)
tldr cfg <file> <function>
tldr cfg src/processor.py process_data
# Returns: cyclomatic complexity, blocks, branches, loops

# Data flow graph (variable tracking)
tldr dfg <file> <function>
tldr dfg src/processor.py process_data
# Returns: where variables are defined, read, modified

# Program slice (what affects line X)
tldr slice <file> <function> <line>
tldr slice src/processor.py process_data 42
tldr slice src/processor.py process_data 42 --direction forward
tldr slice src/processor.py process_data 42 --var result

コードベース分析

# Build cross-file call graph
tldr calls [path]
tldr calls src/ --lang python

# Reverse call graph (who calls this function?)
tldr impact <func> [path]
tldr impact process_data src/ --depth 5
tldr impact authenticate . --file auth  # Filter by file

# Find dead/unreachable code
tldr dead [path]
tldr dead src/ --entry main cli test_  # Specify entry points
tldr dead . --lang typescript

# Detect architectural layers
tldr arch [path]
tldr arch src/ --lang python
# Returns: entry layer, middle layer, leaf layer, circular deps

インポート分析

# Parse imports from file
tldr imports <file>
tldr imports src/api.py
tldr imports src/api.ts --lang typescript

# Reverse import lookup (who imports this module?)
tldr importers <module> [path]
tldr importers datetime src/
tldr importers UserService . --lang typescript

品質とテスト

# Type check + lint
tldr diagnostics <file|path>
tldr diagnostics src/api.py
tldr diagnostics . --project              # Whole project
tldr diagnostics src/ --no-lint           # Type check only
tldr diagnostics src/ --format text       # Human-readable

# Find affected tests
tldr change-impact [files...]
tldr change-impact                        # Auto-detect (session/git)
tldr change-impact src/api.py             # Explicit files
tldr change-impact --session              # Session-modified files
tldr change-impact --git                  # Git diff files
tldr change-impact --git --git-base main  # Diff against branch
tldr change-impact --run                  # Actually run affected tests

キャッシュ

# Pre-build call graph cache
tldr warm <path>
tldr warm src/ --lang python
tldr warm . --background                  # Build in background

# Build semantic index (one-time)
tldr semantic index [path]
tldr semantic index . --lang python
tldr semantic index . --model all-MiniLM-L6-v2  # Smaller model (80MB)

---

デーモン（クエリの高速化）

デーモンはインデックスをメモリ上に保持し、繰り返し実行するクエリに即座に応答します。

デーモンコマンド

# Start daemon (backgrounds automatically)
tldr daemon start
tldr daemon start --project /path/to/project

# Check status
tldr daemon status

# Stop daemon
tldr daemon stop

# Send raw command
tldr daemon query ping
tldr daemon query status

# Notify file change (for hooks)
tldr daemon notify <file>
tldr daemon notify src/api.py

デーモンの機能

機能	説明
自動シャットダウン	30 分間アイドル状態が続くと実行
クエリのキャッシュ	SalsaDB のメモ化
コンテンツのハッシュ化	変更されていないファイルをスキップ
変更状態の追跡	増分再インデックス
クロスプラットフォーム	Unix ソケット／Windows TCP

デーモンソケットプロトコル

ソケットに JSON を送信し、JSON の応答を受信します。

// Request
{"cmd": "search", "pattern": "process", "max_results": 10}

// Response
{"status": "ok", "results": [...]}

デーモンコマンド全 22 種：

ping, status, shutdown, search, extract, impact, dead, arch,
cfg, dfg, slice, calls, warm, semantic, tree, structure,
context, imports, importers, notify, diagnostics, change_impact

---

セマンティック検索（P6）

埋め込み表現を使用した自然言語によるコード検索です。

セットアップ

# Build index (downloads model on first run)
tldr semantic index .

# Default model: bge-large-en-v1.5 (1.3GB, best quality)
# Smaller model: all-MiniLM-L6-v2 (80MB, faster)
tldr semantic index . --model all-MiniLM-L6-v2

検索

tldr semantic search "authentication flow"
tldr semantic search "error handling patterns" --k 10
tldr semantic search "database connection" --expand  # Follow call graph

設定

.claude/settings.json に記述します。

{
  "semantic_search": {
    "enabled": true,
    "auto_reindex_threshold": 20,
    "model": "bge-large-en-v1.5"
  }
}

---

サポート対象言語

言語	AST	呼び出しグラフ	CFG	DFG	PDG
Python	Yes	Yes	Yes	Yes	Yes
TypeScript	Yes	Yes	Yes	Yes	Yes
JavaScript	Yes	Yes	Yes	Yes	Yes
Go	Yes	Yes	Yes	Yes	Yes
Rust	Yes	Yes	Yes	Yes	Yes
Java	Yes	Yes	-	-	-
C/C++	Yes	Yes	-	-	-
Ruby	Yes	-	-	-	-
PHP	Yes	-	-	-	-
Kotlin	Yes	-	-	-	-
Swift	Yes	-	-	-	-
C#	Yes	-	-	-	-
Scala	Yes	-	-	-	-
Lua	Yes	-	-	-	-
Elixir	Yes	-	-	-	-

---

無視するパターン

TLDR は .tldrignore（gitignore 構文）に従います。

# .tldrignore
.venv/
__pycache__/
node_modules/
*.min.js
dist/

初回実行時に、妥当なデフォルトを設定した .tldrignore が作成されます。 無視設定をバイパスするには --no-ignore を使用します。

---

TLDR と他のツールの使い分け

タスク	TLDR を使用	Grep を使用
関数定義を見つける	tldr extract file --function X	-
コードパターンを検索する	tldr search "pattern"	-
文字列リテラルを検索する	-	grep "literal"
設定値を検索する	-	grep "KEY="
ファイル間の呼び出しを調べる	tldr calls	-
逆依存関係を調べる	tldr impact func	-
複雑度を分析する	tldr cfg file func	-
変数を追跡する	tldr dfg file func	-
自然言語でクエリする	tldr semantic search	-

---

Python API

from tldr.api import (
    # L1: AST
    extract_file, extract_functions, get_imports,
    # L2: Call Graph
    build_project_call_graph, get_intra_file_calls,
    # L3: CFG
    get_cfg_context,
    # L4: DFG
    get_dfg_context,
    # L5: PDG
    get_slice, get_pdg_context,
    # Unified
    get_relevant_context,
    # Analysis
    analyze_dead_code, analyze_architecture, analyze_impact,
)

# Example: Get context for LLM
ctx = get_relevant_context("src/", "main", depth=2, language="python")
print(ctx.to_llm_string())

---

バグ修正ワークフロー（ナビゲーション + 読み込み）

重要なポイント： TLDR で場所を特定してから、自分で読みます。要約だけを頼りにバグを修正しようとしないでください。

パターン

# 1. NAVIGATE: Find which files matter
tldr imports file.py              # What does buggy file depend on?
tldr impact func_name .           # Who calls the buggy function?
tldr calls .                      # Cross-file edges (follow 2-hop for models)

# 2. READ: Get actual code for critical files (2-4 files, not all 50)
# Use Read tool or tldr search -C for code with context
tldr search "def buggy_func" . -C 20

この方法が有効な理由

ファイルをまたぐバグ（例：フィールド名の誤り、型の不一致）では、次の内容を確認する必要があります。

• バグがあるファイル（task.user_id にアクセスしているハンドラー）
• 契約を定義するファイル（owner_id を定義しているモデル）

TLDR で関係するファイルを特定し、その後にファイルを読みます。

コンテキストをさらに確認する

TLDR の出力だけでは不十分な場合：

• tldr search "pattern" . -C 20 - 前後 20 行のコンテキストを含む実際のコードを取得します
• tldr imports file.py - ファイルが依存しているものを確認します
• 実装全体が必要な場合は、ファイルを直接読みます

トークン削減の根拠

Raw file read:    23,314 tokens
TLDR all layers:   1,189 tokens
─────────────────────────────────
Savings:              95%

ポイント：呼び出しグラフで関連するコードに移動し、その後、レイヤーごとに構造化された要約を確認します。無関係なコードを読む必要はありません。