xonecas.io
5745
Sc

sacenox.github.io / files

sacenox.github.io / _posts / 2026-02-03-opencode-setup-guide.md

6.6 KB
1---
2layout: post
3title: building-a-production-ready-opencode-configuration-from-scratch
4description: A deep dive into cost optimization, workflows, and skills for OpenCode.
5---
6
7# Building a Production-Ready OpenCode Configuration from Scratch
8
9Setting up an AI coding assistant isn't just about picking a model and starting to code. After spending time configuring OpenCode from the ground up, I learned that a thoughtful setup can save you money, improve code quality, and create a more disciplined development workflow.
10
11Here's how I built a comprehensive OpenCode configuration that balances cost efficiency with powerful capabilities.
12
13## The Foundation: Global Rules and Workflow
14
15The first step was creating a global `AGENTS.md` file at `~/.config/opencode/AGENTS.md`. This isn't just documentation—it's the behavioral contract for all AI interactions.
16
17### Core Principles
18
19I established several non-negotiable rules:
20- Professional tone (no "You're absolutely right!" responses)
21- No emojis or AI-speak
22- Documentation-first approach
23- No auto-commits without explicit approval
24- Always work within the current repo's root
25
26### The Six-Phase Workflow
27
28The real breakthrough was implementing a structured development workflow:
29
301. **Plan** - Use Plan mode for gathering information and creating detailed plans
312. **Validate** - Verify assumptions before building
323. **Build** - Implement with discipline to return to Plan if issues arise
334. **Review** - Use the built-in `/review` command (a hidden gem I discovered)
345. **Document** - Update AGENTS.md, README.md, and inline docs
356. **Complete** - Provide verification evidence before claiming "done"
36
37This workflow prevents the common AI pitfall of pushing through problems blindly.
38
39## Configuration: opencode.json Optimization
40
41The `opencode.json` file is where the magic happens. Here's what I learned about model selection and cost optimization.
42
43### Model Selection Strategy
44
45I started with Claude Sonnet 4.5 at $3.00/$15.00 per 1M tokens, but the costs were adding up fast. After analyzing usage patterns, I discovered that cache reads were dominating my bill—534M cache reads in typical usage.
46
47The breakthrough came with Gemini 3 Flash at $0.50/$3.00 per 1M tokens. This represented an 80% cost reduction while maintaining quality for most coding tasks.
48
49### Smart Configuration Choices
50
51```json
52{
53  "provider": "opencode-zen",
54  "default_model": "opencode/gemini-3-flash",
55  "small_model": "opencode/gpt-5-nano",
56  "instructions": [
57    "CONTRIBUTING.md",
58    "docs/guidelines.md",
59    ".cursor/rules/*.md"
60  ],
61  "agent_temperatures": {
62    "plan": 0.1,
63    "build": 0.3
64  }
65}
66```
67
68Key insights:
69- Use a free model (GPT 5 Nano) for simple tasks like title generation
70- Auto-load project documentation with the `instructions` array
71- Different temperatures for different modes (lower for planning, higher for creative building)
72- Git permission rules requiring approval for destructive operations
73
74## Skills: The Secret Weapon
75
76The skills ecosystem through `skills.sh` was a game-changer. I installed seven carefully chosen skills:
77
78### Core Skills Installed
79
80- **systematic-debugging** - Methodical approach to problem-solving
81- **verification-before-completion** - QA discipline before claiming "done"
82- **writing-plans** - Structured planning methodology
83- **commit-work** - Git commit discipline and best practices
84- **crafting-effective-readmes** - Documentation standards
85- **mermaid-diagrams** - Visual documentation tools
86- **writing-clearly-and-concisely** - Communication improvement
87
88### Installation Strategy
89
90I used the `npx skills -g` command to install skills globally, then copied them as actual files (not symlinks) for portability across machines. This ensures the configuration works identically on any development environment.
91
92## Hidden Features and Discoveries
93
94### The /review Command
95
96OpenCode has a built-in `/review` command that I wish I'd discovered earlier. It can review changes at different scopes:
97- `review changes` - Uncommitted changes (default)
98- `review changes commit` - Last commit
99- `review changes branch` - Current branch vs main
100- `review changes pr` - Pull request changes
101
102This eliminates the need for manual code review workflows.
103
104### Model Naming Convention
105
106OpenCode Zen uses a specific naming convention with the "opencode/" prefix. This caught me off guard initially—make sure to use names like `opencode/gemini-3-flash`, not just `gemini-3-flash`.
107
108## Cost Analysis and Optimization
109
110The numbers tell the story. My original configuration would have cost roughly $50-80 per month for heavy usage. The optimized setup reduced this to $10-15 per month—a 75-80% savings.
111
112### Cost Factors to Consider
113
114- **Input tokens** - Your code and prompts
115- **Output tokens** - AI responses
116- **Cache reads** - Often the biggest cost factor
117- **Model capabilities** - Balance cost vs. quality needs
118
119The key insight: cache reads can dominate your bill. Choose models with favorable cache pricing, and Gemini 3 Flash excels here.
120
121## Final Directory Structure
122
123```
124~/.config/opencode/
125├── AGENTS.md          # Global rules and workflow (63 lines)
126├── opencode.json      # Optimized configuration
127├── agents/
128│   └── writer.md      # Specialized subagents
129└── skills/            # Portable skill library
130    ├── commit-work/
131    ├── crafting-effective-readmes/
132    ├── mermaid-diagrams/
133    ├── systematic-debugging/
134    ├── verification-before-completion/
135    ├── writing-clearly-and-concisely/
136    └── writing-plans/
137```
138
139## Lessons Learned
140
1411. **Start with discipline** - Rules and workflow matter more than model choice
1422. **Monitor costs actively** - Usage patterns reveal optimization opportunities
1433. **Skills are force multipliers** - The ecosystem provides battle-tested methodologies
1444. **Documentation is configuration** - AGENTS.md shapes AI behavior as much as JSON settings
1455. **Hidden features exist** - Explore built-in commands like `/review`
146
147## Next Steps
148
149This configuration provides a solid foundation, but it's designed to evolve. As new models become available and costs change, the structure supports easy updates. The workflow ensures quality remains high regardless of the underlying technology.
150
151The investment in setup pays dividends in every subsequent coding session. Professional AI assistance isn't just about having access to models—it's about creating systems that amplify your capabilities while maintaining discipline and cost control.
152
153## Sources
154
155- OpenCode documentation and configuration reference
156- skills.sh ecosystem and skill library
157- OpenCode Zen pricing analysis and model comparisons
158- Personal configuration testing and cost optimization experiments