rynhardt-potgieter CLI Agent Patterns — Efficient Tool Usage for LLM Agents
LLM agents that use CLI tools for code intelligence, search, or project management need disciplined usage patterns. Every tool call consumes tokens and latency. This skill defines how agents should select, sequence, and limit CLI tool calls for maximum efficiency.
Decision Tree — Match Task to ONE Command
Start every complex task with an overview command (e.g., project map, directory listing, status check). This gives you the full context in minimal tokens. Then use ONE specific command for your task:
| Task Type | Approach | When Done? |
|---|---|---|
| Orientation / start of any task | Overview/map command | One call. Shows architecture, entry points, key files. |
| Find callers/consumers of a function | Caller/reference lookup | One call. Output has file paths + line numbers + snippets. |
| Understand a class/module structure | Structural overview (sketch/outline) | One call. Shows methods, signatures, dependencies. |
| Find code by intent/description | Semantic or full-text search | One call. Searches names, signatures, descriptions. |
| Find entry points (controllers, handlers) | Entry point listing | One call. Groups by type: API, workers, handlers. |
| Blast radius / transitive impact | Deep caller/dependency lookup | One call with depth parameter. |
| Bug fix / trace call chain | Trace or call-path command | One call. Shows every path from entry point to symbol. |
| Refactor a method signature | Caller/reference lookup | One call. Gives you every call site to update. |
| PR triage / what changed | Diff or changed-files command | One call. Shows affected symbols in changed files. |
| Read actual source of a symbol | Source/cat command | One call. Prints full source for a specific symbol. |
| Find similar implementations | Similarity search | One call. Finds structurally similar code. |
Workflows by Task Type
These workflows are optimal action sequences. Follow them exactly.
Discovery — "Find X and modify it"
search "<description>" # 1 command: locate the code
-> Read the target file # 1 read: understand the implementation
-> EDIT # Act immediately
Total: 1 tool command + 1-3 reads + edits. Do NOT run a structural overview after search.
Bug Fixing — "X is broken, find and fix it"
trace/call-path <symbol> # 1 command: see how requests reach the code
-> Read the suspected file # 1-2 reads: find the actual bug
-> EDIT # Fix it
Total: 1 tool command + 2-3 reads + edit. Do NOT get a structural overview -- you need the source code, not a summary. If you don't know the symbol name, search first, then trace.
PR Review — "What changed and what's affected?"
diff command # 1 command: symbols in changed files
-> overview of changed class # 1-2 overviews: understand affected symbols
-> Review / comment # Act
Total: 1 diff + 1-2 overviews. Do NOT read every changed file -- diff tells you what symbols were affected, overview tells you the structure.
Reading Source — "I need the actual code for this symbol"
source <symbol> # 1 command: prints the full source
-> EDIT # Modify directly
Use source lookup when you've already navigated (via overview, search, or trace) and need the actual implementation. Skips the overhead of reading the entire file.
Refactoring — "Restructure X to pattern Y"
structural overview <class> # 1 command: understand the current structure
-> Read the target file # 1 read: see the code you'll change
-> Read related files # 2-3 reads: understand consumers/dependencies
-> EDIT (multiple files) # Restructure
Total: 1 tool command + 3-5 reads + edits. Overview gives you the structure; then read files you'll actually modify.
New Feature — "Build something integrating X, Y, Z"
project overview # 1 command: understand the architecture
overview <ServiceA> # 1 overview per API you need to integrate
overview <ServiceB> # (typically 3-4 overviews)
overview <ServiceC> #
-> Read 1-2 pattern files # See how existing integrations work
-> EDIT / Write new files # Build the feature
Total: 1 project overview + 3-4 overviews + 1-2 reads + edits. This is the sweet spot -- 17-30% token savings. Overviews give you method signatures and constructor params without reading 100+ line files.
Exploration — "Document or explain the architecture"
project overview # 1 command: full architecture overview
entry point listing # 1 command: all entry points grouped by type
-> Read 2-3 key files # Only the files you need specific details from
-> Write documentation # Act
Total: 2 commands + 2-3 reads + write. Do NOT overview every class -- the project map already has the overview. Read files only for specific implementation details that the map doesn't cover.
Compounding Rules
Good compounds (use these)
- Project overview -> specific class overview -- overview first, then drill into one class
- Search -> trace -- discover, then trace the call path
- Caller lookup -> caller class overview -- find callers, then understand one caller's context
- Project overview -> entry point listing -- for exploration tasks needing both overview and entry point detail
- Diff -> changed class overview -- PR triage: what changed, then understand affected structure
- Structural overview -> source lookup -- understand structure first, then get actual code when needed
Bad compounds (never do these)
- Overview X -> Read X -- if you're going to read it, skip the overview
- Search X -> Grep X -- redundant; search already searched
- Callers X -> All-references X -- callers is a subset of references
- Overview A -> Overview B -> Overview C -> ... (5+) -- over-navigating; use project overview instead
- Trace X -> Callers X -> Overview X -- pick ONE, not three
The 3-Command Limit
If you've run 3 tool commands and haven't edited a file yet, stop navigating and start editing. The output from your first command almost certainly had enough information. Agents that follow this rule use 30% fewer tokens.
Anti-Patterns — What NOT to Do
- Don't run overlapping lookups for the same symbol (e.g., callers AND all-references) -- one is a subset of the other.
- Don't use deep traversal for simple "find and update" tasks -- shallow lookup is sufficient.
- Don't overview what you'll Read -- overview is for understanding WITHOUT opening the file.
- Don't run 5+ tool commands for any task -- if you need that many, you're exploring for its own sake.
- Don't ignore source snippets in lookup output -- they show the usage pattern without needing to open the file.
- Don't search when you know the symbol name -- use direct lookup instead.
- Don't skip the project overview for complex tasks -- it replaces 5-17 individual overviews with one command.
Token Efficiency Checklist
Before running a tool command, ask yourself:
- Do I already have this information from a previous command? -> Don't run it.
- Will my next action be reading the file anyway? -> Skip the overview.
- Am I running this "just in case"? -> Don't. Run it when you need it.
- Have I already run 2+ commands without editing? -> Start editing.
- Could a project overview replace the 3+ individual overviews I'm about to run? -> Use the overview.
Designing CLI Tools for Agent Consumption
When building CLI tools that agents will use:
- Include file paths and line numbers in all output -- agents need these to navigate.
- Include source snippets in reference/caller output -- avoids a second read.
- Support JSON output on every command -- agents can parse structured data more reliably.
- Write help text for LLM readers -- the
--helptext is how the agent learns to use the tool. Be specific about what the output looks like and when to use the command. - Truncate with counts -- show "... 15 more (use --limit)" not silent truncation.
- Keep output compact -- overview commands should fit in ~500 tokens.
- Never require interactive input -- agents run non-interactively.
- Separate data from progress -- data to stdout, progress to stderr, so JSON output is always clean.