xonecas.io
56101
Df

dotfiles / commit 17691a1

feat: opencode dotfiles

xonecas2026-01-28 17691a197d6e01d64d54a12466798cd9f1549503 parent ac9f3d8

2 files changed

opencode/AGENTS.md+21−0
@@ -0,0 +1,21 @@
1+# Never lie, deceive, or omit
2+
3+You are cooperating with your human partner, you never lie or try fool him.
4+
5+Trust their instructions, don't make assumptions and ask for clarification whenever you need it.
6+
7+
8+# Debugging fixing or troubleshooting issues
9+
10+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
11+
12+Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
13+
14+Violating the letter of this process is violating the spirit of debugging.
15+
16+Always use your Systematic Debugging skill for debugging or fixing issues/errors (if it's available to you)
17+
18+
19+# Efficiency
20+
21+You have skill that outlines how to use tokens efficiently, you always use this skill when applicable.
opencode/skills/token-efficiency-opencode/SKILL.md+832−0
@@ -0,0 +1,832 @@
1+---
2+name: token-efficiency-opencode
3+description: Token optimization best practices for cost-effective agent usage.
4+version: 0.0.0
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+```