@@ -1,832 +0,0 @@
1----
2-name: token-efficiency-opencode
3-description: Load before any file operation, codebase exploration, or task involving large outputs. Provides strategies to minimize token usage by 90%+ through smart filtering, parallel calls, and avoiding full file reads.
4-version: 0.0.1
5----
6-
7-# Token Efficiency Expert
8-
9-Token optimization strategies to minimize cost without sacrificing quality.
10-
11-## Core Principle
12-
13-**Default to these guidelines unless the user requests verbose output or full file contents.**
14-
15-Default assumption: **Users prefer efficient, cost-effective assistance.**
16-
17-**OpenCode environment:** Always use structured tools (`Read`, `Grep`, `Glob`, `Edit`, `Write`) instead of shell text utilities (`cat`, `grep`, `find`, `sed`, `awk`). Use bash only for actual terminal operations (git, npm, docker, etc.).
18-
19----
20-
21-## Quick Reference Card
22-
23-**Before ANY file operation, ask yourself:**
24-
25-1. Can I use Task/explore for this codebase question?
26-2. Can I avoid streaming file contents?
27-3. Can I filter before reading?
28-4. Is a small, targeted read enough?
29-5. Does the user need full content?
30-
31-**Default strategy:**
32-1. **Exploratory questions** → Use `Task(subagent_type="explore")`
33-2. **Specific files/patterns** → Use `Glob`/`Grep`/`Read(limit)`
34-3. **Full reads** → Only when required or requested
35-
36-**Common patterns:**
37-```bash
38-# Exploring codebase
39-Task(subagent_type="explore", prompt="How does auth work?")
40-
41-# Finding files
42-Glob: "**/*.py"
43-
44-# Searching content
45-Grep: "def my_function" (include="*.py")
46-
47-# Reading strategically
48-Read: large_file.py (limit: 100)
49-Read: large_file.py (offset: 500, limit: 100)
50-
51-# Editing (always read first)
52-Read: config.py
53-Edit: config.py (oldString="...", newString="...")
54-```
55-
56-**Core motto: Use Task for exploration. Filter first. Read selectively. Summarize intelligently.**
57-
58----
59-
60-## Token Optimization Rules
61-
62-### 1. Use Task Tool for Codebase Exploration
63-
64-**CRITICAL for OpenCode:** When exploring codebases to gather context or answer questions that aren't needle queries for specific files, **ALWAYS use the Task tool** with the explore agent.
65-
66-This is OpenCode's most powerful token optimization - the explore agent handles all the searching, reading, and filtering internally, returning only relevant findings.
67-
68-**When to use Task/explore (REQUIRED):**
69-- ✅ "How does X work in this codebase?"
70-- ✅ "Where are errors from Y handled?"
71-- ✅ "What is the structure of Z?"
72-- ✅ "How are API endpoints organized?"
73-- ✅ Any exploratory question requiring multiple rounds of searching
74-- ✅ Understanding unfamiliar codebases
75-- ✅ Finding patterns across multiple locations
76-- ✅ Questions that would require 3+ Grep/Read operations
77-
78-```python
79-# ✅ DO: Use Task for exploration
80-Task(
81- subagent_type="explore",
82- description="Research auth handling",
83- prompt="""Explore the codebase (thoroughness: medium).
84-Find how authentication is handled - auth flow, token storage, error handling.
85-Return file paths and key findings."""
86-)
87-
88-# ❌ DON'T: Manual exploration (wastes tokens)
89-Grep: "auth" (include="*.py")
90-Read: file1.py
91-Read: file2.py
92-Grep: "token" (include="*.py")
93-Read: file3.py
94-# ... multiple rounds of search/read
95-```
96-
97-**When to use direct tools instead:**
98-- ✅ "Read file at path X" → Use `Read` (you know exact location)
99-- ✅ "Find class Foo" → Use `Glob("**/foo.py")` or `Grep("class Foo")` (needle query)
100-- ✅ "Search for string in this specific file" → Use `Grep(pattern, path="file.py")`
101-- ✅ You already know the exact file from previous context
102-
103-**Rule of thumb:** If the question would require you to search, then read, then search again, then read again → **Use Task/explore first.**
104-
105----
106-
107-### 2. Use Parallel Tool Calls
108-
109-**OpenCode optimization:** When calling multiple tools with no dependencies between them, make all calls in parallel by sending them in a single message.
110-
111-```python
112-# ✅ Efficient - parallel execution (single message, multiple tools)
113-Read: src/config.py
114-Read: src/utils.py
115-Read: tests/test_main.py
116-# All three execute simultaneously
117-
118-# ❌ Less efficient - sequential messages
119-# Message 1: Read: src/config.py
120-# Wait for result...
121-# Message 2: Read: src/utils.py
122-# Wait for result...
123-# Message 3: Read: tests/test_main.py
124-```
125-
126-**When to use parallel:**
127-- Reading multiple independent files
128-- Running multiple independent bash commands
129-- Launching multiple Task agents
130-- Any operations where results don't depend on each other
131-
132-**When to use sequential:**
133-- Later calls need data from earlier results
134-- Operations must complete in order (e.g., Read before Edit)
135-- One operation depends on success of another
136-
137----
138-
139-### 3. Always Read Before Edit or Write
140-
141-**OpenCode requirement:** You MUST use `Read` before `Edit` or `Write` on existing files. Attempting to edit without reading will fail.
142-
143-This requirement actually **saves tokens** - it prevents blind edits that might fail due to incorrect assumptions about file content.
144-
145-```python
146-# ✅ Correct workflow
147-Read: config.py
148-Edit: config.py (oldString="DEBUG = False", newString="DEBUG = True")
149-
150-# ❌ Will fail - no prior Read
151-Edit: config.py (oldString="DEBUG = False", newString="DEBUG = True")
152-
153-# ✅ Creating new files (no Read required)
154-Write: new_file.py (content="...")
155-```
156-
157-**Why this saves tokens:**
158-- Prevents failed edits and retry loops
159-- Ensures you have correct context for oldString
160-- Catches files that don't exist or have different content than expected
161-
162----
163-
164-### 4. Use Quiet/Minimal Output Modes
165-
166-**For commands with `--quiet`, `--silent`, or `-q` flags:**
167-
168-```bash
169-# ❌ DON'T: Use verbose mode by default
170-command --verbose
171-
172-# ✅ DO: Use quiet mode by default
173-command --quiet
174-command -q
175-command --silent
176-```
177-
178-**Common commands with quiet modes:**
179-- `git -q`, `curl -s`, `wget -q`, `make -s`
180-- custom scripts with `--quiet`
181-
182-**When to use verbose:** Only when user explicitly asks for detailed output.
183-
184----
185-
186-### 5. NEVER Read Entire Log Files
187-
188-**Log files can be 50-200K tokens. ALWAYS filter before reading.**
189-
190-```bash
191-# ❌ NEVER DO THIS:
192-Read: /var/log/application.log
193-Read: debug.log
194-Read: error.log
195-
196-# ✅ ALWAYS DO ONE OF THESE:
197-
198-# Option 1: Read only the end (most recent)
199-Read: /var/log/application.log (offset: 4900, limit: 100)
200-
201-# Option 2: Filter for errors/warnings first
202-Grep: "(?i)error|fail|warning" (path="/var/log/application.log")
203-# Then read context around found lines:
204-Read: /var/log/application.log (offset: 850, limit: 30)
205-
206-# Option 3: Specific time range (if timestamps present)
207-Grep: "2026-01-28" (path="/var/log/application.log")
208-
209-# Option 4: Count occurrences first to gauge scope
210-Bash: rg -c "ERROR" /var/log/application.log
211-# Output: 245
212-# Now you know there are many errors, read a sample:
213-Read: /var/log/application.log (offset: 4950, limit: 50)
214-```
215-
216-**Exceptions:** Read the full log only if the user explicitly requests it, filtered output lacks critical context, or the log is confirmed small (<1000 lines).
217-
218----
219-
220-### 3. Check Lightweight Sources First
221-
222-**Before reading large files, check if info is available in smaller sources:**
223-
224-**For Git repositories:**
225-```bash
226-# ✅ Check status first (small output)
227-Bash: git status --short
228-Bash: git log --oneline -10
229-
230-# ❌ Don't immediately read
231-Read: .git/logs/HEAD # Can be large
232-```
233-
234-**For Python/Node projects:**
235-```bash
236-# ✅ Check package info (small files)
237-Bash: jq '.dependencies' package.json
238-Read: requirements.txt (limit: 20)
239-
240-# ❌ Don't immediately read
241-Read: node_modules/ # Huge directory
242-Read: venv/ # Large virtual environment
243-```
244-
245-**For long-running processes:**
246-```bash
247-# ✅ Check process status
248-Bash: ps -eo pid,comm,pcpu,pmem --sort=-pcpu
249-
250-# ❌ Don't read full logs immediately
251-Read: /var/log/syslog
252-```
253-
254----
255-
256-### 4. Use Search Tools Instead of Reading Files
257-
258-**When searching for specific content:**
259-
260-```bash
261-# ❌ DON'T: Read file then manually search
262-Read: large_file.py # 30K tokens
263-# Then manually look for "def my_function"
264-
265-# ✅ DO: Use Grep/Search to find it
266-Grep: "def my_function" large_file.py
267-# Then read only the relevant section if needed
268-Read: large_file.py (offset: <line-5>, limit: 20)
269-```
270-
271-**Advanced search usage:**
272-```bash
273-Grep: "TODO" path="src" include="*.py"
274-Grep: "(?i)error" path="." include="*.log"
275-Bash: rg -c "import" *.py
276-```
277-
278----
279-
280-### 5. Read Files with Limits
281-
282-**If you must read a file, use offset and limit parameters:**
283-
284-```bash
285-# ✅ Read first 100 lines to understand structure
286-Read: large_file.py (limit: 100)
287-
288-# ✅ Read specific section
289-Read: large_file.py (offset: 500, limit: 100)
290-
291-# ✅ Read just the imports/header
292-Read: script.py (limit: 50)
293-```
294-
295-**For very large files:**
296-```bash
297-# Check file size first
298-Bash: wc -l large_file.txt
299-# Output: 50000 lines
300-
301-# Then read strategically
302-Read: large_file.txt (limit: 100) # Beginning
303-Read: large_file.txt (offset: 1000, limit: 100) # Specific middle section
304-```
305-
306-**Large test outputs (example):**
307-```python
308-Read(file_path, limit=10)
309-Read(file_path, offset=140, limit=120)
310-Grep: "test_index" tool_test_output.json
311-```
312-Targeted reads typically save 90%+ tokens versus full reads.
313-
314----
315-
316-### 6. Avoid Streaming File Content into the Model
317-
318-**CRITICAL OPTIMIZATION:** Prefer operations that do not emit file contents to the model context. These are near-zero token cost and scale well.
319-
320-#### Common Low-Token File Operations
321-
322-Use non-streaming bash operations for simple file management:
323-
324-```bash
325-# ✅ Copy/move/rename (no content streaming)
326-Bash: cp source_file.txt destination_file.txt
327-Bash: mv old_name.py new_name.py
328-Bash: rm temp_file.txt
329-Bash: mkdir -p src/components
330-
331-# ✅ Append without reading
332-Bash: cat >> log.txt << 'EOF'
333-New log entry
334-EOF
335-
336-# ✅ Count lines without reading
337-Bash: wc -l document.txt
338-
339-# ✅ Check file size without reading
340-Bash: du -h large_file.csv
341-Bash: stat -c%s file.bin # Size in bytes
342-```
343-
344-#### Bulk Text Changes Across Multiple Files
345-
346-**For simple find/replace across many files:**
347-
348-```bash
349-# ✅ Pure textual replacement (no structure/logic needed)
350-Bash: find src -name "*.py" -exec sed -i 's/old_text/new_text/g' {} +
351-
352-# ✅ Rename variables across files (simple text)
353-Bash: rg -l "oldVarName" src/ | xargs sed -i 's/oldVarName/newVarName/g'
354-
355-# ❌ DON'T use Edit for many files (streams all content)
356-Read: file1.py
357-Edit: file1.py (...)
358-Read: file2.py
359-Edit: file2.py (...)
360-# ... for 50 files = massive token cost
361-```
362-
363-#### When to Use Read/Edit Instead of sed
364-
365-Use structured `Read`/`Edit` tools when:
366-
367-1. **Code-aware changes needed** - Indentation, syntax structure matters
368-2. **Must validate before modifying** - Need to check current state
369-3. **Logic-dependent changes** - Change depends on surrounding code
370-4. **User wants to review** - Show what will change
371-5. **Complex replacements** - Multi-line, context-sensitive
372-
373-```python
374-# ✅ Use Edit: Complex, code-aware change
375-Read: module.py
376-Edit: module.py (
377- oldString="def old_function(x):\n return x * 2",
378- newString="def new_function(x: int) -> int:\n return x * 2"
379-)
380-
381-# ✅ Use sed: Simple text replacement across many files
382-Bash: find . -name "*.md" -exec sed -i 's/http:/https:/g' {} +
383-```
384-
385-#### Decision Tree for File Changes
386-
387-**Ask yourself:**
388-1. Is this pure text replacement? → **sed** (fastest, lowest tokens)
389-2. Do I need to see the content first? → **Read + Edit** (safe, validated)
390-3. Is it code structure change? → **Read + Edit** (preserves syntax)
391-4. Multiple files, simple text? → **sed/find** (scales well)
392-5. Few files, complex logic? → **Read + Edit** (accurate)
393-
394-#### Find CSV Column Indices
395-
396-```bash
397-# ✅ Extract and number header row (no full file read)
398-Bash: python - <<'PY'
399-import csv
400-with open('file.csv', newline='') as f:
401- for i, name in enumerate(next(csv.reader(f)), start=1):
402- print(i, name)
403-PY
404-```
405-Use this to locate columns in wide CSVs without reading data rows.
406-
407-#### Python Data Filtering Pattern
408-
409-Write filtered data to a new file (e.g., `data_filtered.csv`) to preserve the original and make verification easier.
410-
411-#### Handling Shell Aliases in Python Scripts
412-
413-`subprocess.run()` does not expand aliases; use a full executable path instead.
414-
415----
416-
417-### Key Principle for File Operations
418-
419-**Ask yourself first:**
420-1. Can this be done with structured tools (`Glob`, `Grep`, `Read`, `Edit`) or simple file ops (`cp`, `mv`)?
421-2. Is the change purely textual (not logic-dependent)?
422-3. Do I need to see the file content, or just modify it?
423-
424-If answers are YES, YES, NO → **Use structured tools or non-streaming ops, not full reads**
425-
426----
427-
428-### 7. Filter Command Output
429-
430-**For commands that produce large output:**
431-
432-```bash
433-# ❌ DON'T: Capture all output
434-Bash: find / -name "*.py" # Could return 10,000+ files
435-
436-# ✅ DO: Prefer structured tools or narrow scopes
437-Glob: "**/*.py" (path: "/specific/path")
438-Grep: "test" (path: ".", include: "*.py")
439-
440-# ✅ DO: If you must use shell commands, scope tightly
441-Bash: ls -la /specific/path
442-Bash: tree -L 2 /specific/path
443-```
444-
445----
446-
447-### 8. Efficient Todo Management
448-
449-**Keep todos concise to minimize token usage:**
450-
451-```python
452-# ✅ Concise, actionable todos
453-TodoWrite: [
454- {"id": "1", "content": "Fix type error in auth.py:42", "status": "pending"},
455- {"id": "2", "content": "Update API endpoint to v2", "status": "pending"},
456- {"id": "3", "content": "Run tests and fix failures", "status": "pending"}
457-]
458-
459-# ❌ Verbose todos waste tokens
460-TodoWrite: [
461- {"id": "1", "content": "I need to carefully examine the type error that was discovered in the authentication module located in auth.py at line 42 and determine the root cause before implementing a fix", "status": "pending"}
462-]
463-```
464-
465-**Best practices:**
466-- Keep todo content brief (5-10 words max)
467-- Include file:line references for specificity
468-- Update status immediately after completing tasks
469-- Don't batch completions - mark done as you go
470-- Only have ONE task "in_progress" at a time
471-
472-**Token impact:** Concise todos save 50-70% tokens compared to verbose descriptions, especially on long task lists.
473-
474----
475-
476-### 9. Summarize, Don't Dump
477-
478-Summarize key facts and offer to drill down. Avoid pasting long raw outputs or full files unless requested.
479-
480-Example:
481-"487 files total; key items: main.py, tests/, docs/. Want a specific file or type?"
482-
483----
484-
485-### 9. Use Targeted Reads for Large Output
486-
487-**When commands produce large output:**
488-
489-```bash
490-# ✅ Limit output length with targeted reads
491-Read: large_file.txt (limit: 100)
492-Read: large_file.txt (offset: 900, limit: 100)
493-
494-# ✅ Sample from middle
495-Read: large_file.txt (offset: 400, limit: 100)
496-
497-# ✅ Check size before reading
498-Bash: wc -l file.txt
499-# If > 1000 lines, use small limits and offsets
500-```
501-
502----
503-
504-### 10. Use JSON/Data Tools Efficiently
505-
506-**For JSON, YAML, XML files:**
507-
508-```bash
509-# ❌ DON'T: Read entire file
510-Read: large_config.json # Could be 50K tokens
511-
512-# ✅ DO: Extract specific fields
513-Bash: jq '.metadata' large_config.json
514-Bash: jq 'keys' large_config.json # Just see top-level keys
515-Bash: yq '.database.host' config.yaml
516-
517-# For XML
518-Bash: xmllint --xpath '//database/host' config.xml
519-```
520-
521-**For CSV files:**
522-```bash
523-# ❌ DON'T: Read entire CSV
524-Read: large_data.csv # Could be millions of rows
525-
526-# ✅ DO: Sample and analyze
527-Read: large_data.csv (limit: 20) # See header and sample rows
528-Bash: wc -l large_data.csv # Count rows
529-Bash: csvstat large_data.csv # Get statistics (if csvkit installed)
530-```
531-
532----
533-
534-### 11. Optimize Code Reading
535-
536-**For understanding codebases:**
537-
538-```bash
539-
540-# ✅ STEP 1: Get overview
541-Glob: "**/*.py" (path: ".") # List files
542-Grep: "^class " (path: ".", include: "*.py") # List classes
543-Bash: rg "^def " -g "*.py" -c # Count functions per file
544-
545-# ✅ STEP 2: Read structure only
546-Read: main.py (limit: 100) # Just imports and main structure
547-
548-# ✅ STEP 3: Search for specific code
549-Grep: "class MyClass" (path: "src", include: "*.py")
550-
551-# ✅ STEP 4: Read only relevant sections
552-Read: src/mymodule.py (offset: 150, limit: 50) # Just the relevant class
553-
554-# ❌ DON'T: Read entire files sequentially
555-Read: file1.py # 30K tokens
556-Read: file2.py # 30K tokens
557-Read: file3.py # 30K tokens
558-```
559-
560----
561-
562-### 12. Efficient Scientific Literature Searches
563-
564-Batch searches (3-5 at a time), group by taxonomy/topic, and save results after each batch. Track “not found” items to avoid repeats.
565-
566-### Dealing with Session Interruptions
567-
568-When limits are near, save progress, record what’s done/remaining, and write a resume file (e.g., `PROGRESS_YYYYMMDD.md`).
569-
570-### Search Term Iteration
571-
572-If searches fail, broaden terms systematically (species → genus → family). Avoid repeating the same query.
573-
574----
575-
576-## Token Savings Examples
577-
578-Use a short, filtered read instead of a full file:
579-
580-```bash
581-Read: /var/log/app.log (offset: 2000, limit: 50)
582-Grep: "(?i)error|traceback" /var/log/app.log
583-```
584-
585-This pattern typically saves 90%+ tokens versus full reads.
586-
587-## When to Override These Guidelines
588-
589-**Override efficiency rules when:**
590-1. User explicitly requests full output
591-2. Filtered output lacks necessary context
592-3. The file is small (<200 lines)
593-4. The user is in learning mode (understanding structure/patterns)
594-
595-In cases 1-3, ask whether to proceed with a full read vs a filtered view. In learning mode, read a few key files fully, then return to efficient mode.
596-
597----
598-
599-## Strategic File Selection for Learning Mode
600-
601-When entering learning mode, **first determine if this is broad exploration or targeted learning**, then apply the appropriate strategy.
602-
603-### Learning Mode Types
604-
605-**Type 1: Broad Exploration** - "Help me understand this codebase", "How is this organized?"
606-→ Use repository-based strategies below (identify type, read key files)
607-
608-**Type 2: Targeted Pattern Learning** - "How do I implement X?", "Show me examples of Y"
609-→ Use targeted concept search (see Targeted Pattern Learning section below)
610-
611----
612-
613-## Targeted Pattern Learning
614-
615-When user asks about a **specific technique or pattern**, use this focused approach instead of broad exploration.
616-
617-**Opencode note:** Replace shell `grep/find/head` examples below with `Grep` and `Glob` calls, and use `Read` with limits for context.
618-
619-### Examples of Targeted Learning Queries
620-
621-- "How do variable number of outputs work in Galaxy wrappers?"
622-- "Show me how to fetch invocation data from Galaxy API"
623-- "How do I implement conditional parameters in Galaxy tools?"
624-- "How does error handling work in this codebase?"
625-- "Show me examples of async function patterns"
626-- "How are tests structured for workflow X?"
627-
628-### Targeted Learning Workflow
629-
630-1. Identify the concept and likely file types
631-2. Search for 2–3 relevant examples
632-3. Pick the simplest and most recent
633-4. Read those examples fully
634-5. Explain the pattern, variations, and pitfalls
635-
636-Keep the search and read steps small; summarize before expanding.
637-
638----
639-
640-### When to Use Targeted Learning
641-
642-**Use targeted learning when user:**
643- - ✅ Asks how to implement a specific feature or pattern
644-
645-**Don't use for:**
646- - ❌ Broad codebase overview or debugging requests
647-
648----
649-
650-### Key Principles for Targeted Learning
651-
652-Search first, read 2–3 examples, explain the pattern and pitfalls, then confirm what the user needs next.
653-
654----
655-
656-## General Exploration vs Targeted Learning
657-
658-**When user says → Use this approach:**
659-
660-| User Request | Approach | Strategy |
661-|--------------|----------|----------|
662-| "Help me understand this codebase" | **General Exploration** | Identify repo type → Read key files |
663-| "How is this project organized?" | **General Exploration** | Read docs → Entry points → Architecture |
664-| "Show me how to implement X" | **Targeted Learning** | Search for X → Read examples → Extract pattern |
665-| "How does feature Y work?" | **Targeted Learning** | Grep for Y → Find best examples → Explain |
666-| "What patterns are used here?" | **General Exploration** | Read core files → Identify patterns |
667-| "How do I use API method Z?" | **Targeted Learning** | Search for Z usage → Show examples |
668-
669----
670-
671-## Broad Repository Exploration
672-
673-When entering broad exploration mode, **first identify the repository context**, then apply the appropriate exploration strategy.
674-
675-**Opencode note:** Use `Glob` and `Grep` instead of `find/grep`, and `Read` with limits instead of `head/tail`.
676-
677-### STEP 1: Identify Repository Type
678-
679-Identify repo type quickly (library, monolith, framework, or examples), then read docs + 2–5 representative files.
680-Summarize patterns and ask where to go deeper.
681-
682----
683-
684-### File Selection Priorities (General Rules)
685-
686-Priorities (in order):
687-1. Documentation (README, CONTRIBUTING, architecture docs)
688-2. Entry points (main/app/run)
689-3. Core components (managers/orchestrators/base classes)
690-4. Representative examples (recent, medium complexity)
691-5. Active areas (recent commits)
692-
693-Keep it to 2–5 files, then summarize and ask where to go deeper.
694-
695----
696-
697-### Key Principle for Learning Mode
698-
699-Read 2–5 key files, summarize patterns, then ask where to go deeper. Avoid reading many files without a plan.
700-
701----
702-
703-## Cost Impact
704-
705-Applying these rules often reduces token usage by 90%+.
706-
707-### Real-World Token Savings Examples
708-
709-**Example 1: Log File Analysis**
710-```bash
711-# ❌ BEFORE (inefficient approach):
712-Read: /var/log/application.log # 50,000 lines = ~150,000 tokens
713-
714-# ✅ AFTER (efficient approach):
715-Grep: "(?i)error" (path="/var/log/application.log") # ~500 tokens
716-Read: /var/log/application.log (offset: 4950, limit: 50) # ~1,500 tokens
717-# Total: ~2,000 tokens saved = 98.7% reduction
718-```
719-
720-**Example 2: Codebase Exploration**
721-```bash
722-# ❌ BEFORE (manual exploration):
723-Grep: "auth" (include="*.py") # ~3,000 tokens
724-Read: src/auth.py # ~8,000 tokens
725-Read: src/middleware.py # ~6,000 tokens
726-Grep: "token" (include="*.py") # ~2,500 tokens
727-Read: src/token_handler.py # ~5,000 tokens
728-# Total: ~24,500 tokens
729-
730-# ✅ AFTER (using Task/explore):
731-Task(subagent_type="explore", prompt="How does auth work?")
732-# Returns summary in ~2,000 tokens
733-# Saved: ~22,500 tokens = 92% reduction
734-```
735-
736-**Example 3: Multiple File Operations**
737-```bash
738-# ❌ BEFORE (sequential reads):
739-# Message 1: Read: config.py (~2,000 tokens)
740-# Message 2: Read: utils.py (~3,000 tokens)
741-# Message 3: Read: tests.py (~4,000 tokens)
742-# Total: ~9,000 tokens + 3 round trips
743-
744-# ✅ AFTER (parallel calls):
745-# Single message with 3 parallel reads
746-Read: config.py
747-Read: utils.py
748-Read: tests.py
749-# Total: ~9,000 tokens + 1 round trip
750-# Saved: 2 round trips + reduced overhead = ~30% faster
751-```
752-
753-**Example 4: Bulk Text Replacement**
754-```bash
755-# ❌ BEFORE (Edit tool for 50 files):
756-Read: file1.py + Edit: file1.py # ~3,000 tokens × 50 files
757-# Total: ~150,000 tokens
758-
759-# ✅ AFTER (sed for simple replacement):
760-Bash: find src -name "*.py" -exec sed -i 's/old/new/g' {} +
761-# Total: ~200 tokens
762-# Saved: ~149,800 tokens = 99.9% reduction
763-```
764-
765-**Cumulative savings in typical session:**
766-- Without token-efficiency: ~200,000 tokens
767-- With token-efficiency: ~15,000 tokens
768-- **Total savings: 92.5%**
769-
770----
771-
772-## Implementation
773-
774-**This skill automatically applies these optimizations when:**
775-- Reading log files
776-- Executing commands with large output
777-- Navigating codebases
778-- Debugging errors
779-- Checking system status
780-
781-**You can always override by saying:**
782-- "Show me the full output"
783-- "Read the entire file"
784-- "I want verbose mode"
785-- "Don't worry about tokens"
786-
787----
788-
789-## Managing Long-Running Background Processes
790-
791-### Best Practices for Background Tasks
792-
793-Keep long-running jobs resumable: record PID/status, save progress, and write a resume note before ending a session.
794-
795----
796-
797-## Repository Organization for Long Projects
798-
799-Keep long projects tidy: use `python_scripts/`, `logs/`, and `tables/` so listing/searching stays small and focused. Organize early or once files start piling up.
800-
801----
802-
803-## Summary
804-
805-**Core motto: Use Task for exploration. Filter first. Read selectively. Summarize intelligently.**
806-
807-**Primary optimization rules (highest impact):**
808-1. **Use Task/explore for codebase questions** - Handles all searching internally
809-2. **Avoid streaming file contents** - Prefer structured tools (Read/Grep/Glob/Edit) and non-streaming file ops (cp/mv/mkdir)
810-3. **Use parallel tool calls** - Call multiple independent tools in one message
811-4. **Always Read before Edit/Write** - Required by OpenCode, prevents failed edits
812-
813-**Secondary rules:**
814-- Never read log files fully - filter first
815-- Use Grep before Read for targeted searches
816-- Read with limits (offset/limit parameters)
817-- Summarize instead of showing raw output
818-- Use quiet modes for commands (git -q, curl -s)
819-- Strategic file selection for learning mode
820-
821-**Typical token savings: 90%+ in large tasks**
822-
823-**Example workflow:**
824-```bash
825-# Exploration
826-Task(subagent_type="explore", prompt="How does auth work?")
827-
828-# Targeted work
829-Grep: "class AuthHandler" (include="*.py")
830-Read: src/auth.py (offset: 100, limit: 50)
831-Edit: src/auth.py (oldString="...", newString="...")
832-```