Common task-oriented recipes using tokenlean tools.
tl advise "understand this repo" # Pick the cheapest first commands
tl pack onboard # One compact onboarding briefing
tl structure # Get the lay of the land
tl entry # Find entry points
tl exports src/lib/ # Understand the public API
tl docs src/utils/ # Read documentation, not code
tl types src/types/ # Understand data shapes
tl schema # Understand the databasetl advise "refactor src/core/auth.ts" # Pick a safe refactor path
tl pack refactor src/core/auth.ts # One compact refactor briefing
tl pack refactor src/core/auth.ts --budget 1200 # Smaller briefing; lower-priority sections omitted
tl impact src/core/auth.ts # What would break?
tl deps src/core/auth.ts # What does it depend on?
tl related src/core/auth.ts # Find the tests
tl coverage src/core/auth.ts # Is it well tested?
tl complexity src/core/auth.ts # How complex is it?tl component src/Button.tsx # Props, hooks, dependencies
tl symbols src/Button.tsx # Function signatures (or src/ for all)
tl symbols src/ --filter function # Functions only across directory
tl history src/Button.tsx # Recent changes
tl blame src/Button.tsx # Who wrote whattl complexity src/ --threshold 15 # Complex functions
tl unused src/ # Dead code
tl todo # Outstanding TODOs
tl hotspots # Frequently changed (unstable?)tl secrets # Scan for hardcoded secrets
tl secrets --staged # Only check staged files
tl secrets --min-severity high # Only high severity issuestl advise "review PR 123" # Pick review commands
tl pack pr 123 # One compact PR briefing
tl pack review # Current branch/staged review context
tl pr feature-branch # Summary of branch changes
tl pr 123 # GitHub PR #123 (needs gh CLI)
tl pr --full # Include files, stats, commits
tl gh pr digest -R owner/repo 123 # Full status: CI, reviews, comments, readiness
tl gh pr comments -R owner/repo 123 --unresolved # Unresolved review threadstl changelog --unreleased # What's new since last tag
tl changelog v0.1.0..v0.2.0 # Between versions
tl changelog --format compact # Quick summary
tl gh release notes -R owner/repo --tag v1.2.0 --dry-run # Preview auto-changelog
tl gh release notes -R owner/repo --tag v1.2.0 # Create GitHub releasetl name coolproject awesomelib # Check npm, GitHub, domains
tl name myapp -s # Suggest variations if taken
tl npm express fastify koa # Compare framework optionstl advise "debug npm test" # Pick debug commands
tl pack debug "npm test" # Test output plus follow-up checks
tl run "npm test" # Summarize test results
tl run "npm run build" # Extract build errors only
tl run "eslint src/" # Summarize lint violations
tl run "npm test" --raw # Full output with stdout/stderr preserved
tl run "npm test" --raw -j # Raw JSON includes separate stdout/stderr fields
tl run "npm test" -j # Structured JSON output
tl tail logs/app.log # Collapse repeats + surface errors/warnings
tl tail logs/app.log -f # Follow file updates with compact summaries
npm test 2>&1 | tl tail # Summarize piped logstl browse https://docs.example.com/api # Fetch docs as markdown
tl context7 react "useEffect" # Look up React docs via Context7
tl context7 nextjs "app router" # Next.js docs
tl npm lodash --deps # Check package dependencies
tl npm chalk --versions # Version history# Read an issue with its direct sub-issues (one API call)
tl gh issue read -R owner/repo 434 # Bodies truncated to 5 lines
tl gh issue read -R owner/repo 434 --no-body # Compact: titles + labels only
tl gh issue read -R owner/repo 434 --full # Complete bodies
# Create issues in bulk from JSON
echo '[{"title":"Bug A","labels":["bug"]},{"title":"Bug B"}]' | \
tl gh issue create-batch -R owner/repo --project edimuj/1
# Create an epic with sub-issues
echo '{"title":"Epic","children":[{"title":"Task 1"},{"title":"Task 2"}]}' | \
tl gh issue create-tree -R owner/repo --project edimuj/1
# Sprint cleanup — close one or more issues with comment
tl gh issue close -R owner/repo 10 11 12 -c "Sprint complete"
# Label triage
tl gh issue label-batch -R owner/repo --add "P1" --remove "triage" 5 6 7
# Land a PR (wait for CI, merge, close linked issues, delete branch)
tl gh pr land -R owner/repo 123 --method squashtl browse https://example.com/docs # Fast: native markdown or HTML conversion
tl browse https://example.com -t 2000 # Limit to ~2000 tokens
tl playwright example.com # Full: headless browser (JS-rendered pages)
tl playwright example.com -s "h1,h2,h3" # Extract headings only
tl playwright example.com --screenshot p # Save screenshot# run without install
npx --package tokenlean tl-audit --latest # Direct binary invocation via npx (binary name)
npx tokenlean audit --all --savings # Package entrypoint via npx
# provider-aware sessions
tl audit --provider claude --latest # Claude Code only
tl audit --codex --latest # Codex only
tl audit --latest --savings # Auto-detect provider; combined summary
tl audit --all --plan # Prioritized recommendations
tl audit --all --plan --github -R owner/repo # Create a GitHub issue from the plan
tl audit --all --plan --github -R owner/repo --github-project owner/1 # Add issue to a project board
# output detail levels
tl audit --all --savings # Summary only, across all matching sessions
tl audit -n 5 --verbose --savings # Add per-session detail
tl audit session.jsonl # Analyze a specific session filetl audit analyzes both Codex and Claude Code sessions:
- Opportunities — tokens wasted on large file reads, verbose build output, raw grep/cat/tail
- Savings (with
--savings) — tokens already saved by tokenlean usage, with capture rate - Plan (with
--plan) — prioritized actions based on the highest saveable categories - Add
--verbosefor per-session breakdown
Summary (270 sessions: 180 Claude Code, 90 Codex)
Still saveable: 496k of 661k (75%)
By provider:
Claude Code 180 sessions 341k saveable 1.5M saved
Codex 90 sessions 155k saveable 820k saved
Already saved: 2.3M (531 tokenlean uses)
Capture rate: 82% of potential savings realized
Install hooks to automatically nudge agents toward token-efficient alternatives:
# Claude Code — PreToolUse hooks (nudge toward better tools)
tl hook install claude-code # Install hooks (auto-detects claude-rig)
tl hook install claude-code --global # Force install to ~/.claude/
tl hook install claude-code --rig dev # Install to a specific rig
tl hook status claude-code # Check what's active
tl hook uninstall claude-code # Remove hooks
# Codex CLI — PreToolUse hooks via ~/.codex/config.toml
tl hook install codex # Install managed Codex hook block
tl hook status codex # Check Codex hook status
tl hook uninstall codex # Remove managed Codex hook block
tl hook status --all # Check all hook adapters
# Open Code — plugin (auto-wraps commands with tl run/tl browse)
tl hook install opencode # Install plugin to ~/.config/opencode/plugins/
tl hook status opencode # Check if installed
tl hook uninstall opencode # Remove plugin