A practical tour of my OpenCode setup with 12 subagents, 123 skills, 16 commands, 8 MCP servers, and a two-layer plain-file memory pipeline.
Table of Content
- TL;DR
- The problem
- Architecture
- Project layout
- The config file
- Core logic
- Operating workflow
- Key decisions
- Mistakes to Avoid
- Checklist
- Quick start
- Verification
- Takeaway
TL;DR
I didn't want a smarter chatbot. I wanted an environment in which AI agents could operate with persistent knowledge, specialised capabilities, controlled permissions and repeatable workflows. So I built it.
The Problem
Out of the box, an AI coding tool is just a chat window. It forgets your conventions between sessions, it has no idea which model is cheap enough for a bulk rename, and it re-learns your repo every time.
I wanted a system that works for me. So I needed the following:
- A config that loads my rules into every tool.
- A roster of cheap and quality subagents, so cost scales with task difficulty.
- Skills that loop with real workflows, tool calls, and a human in the loop, not just prompts.
- MCP servers for docs, search, and filesystem access.
- A memory pipeline that survives context compaction.
Getting Started with OpenCode
OpenCode is not the language model itself. It is the agent runtime. It connects a model to your working directory, instructions, tools, and permissions, then coordinates the work. You choose the provider and model that power the session; OpenCode supports hosted providers as well as local models.
OpenCode really shines once you wire config, subagents, skills, MCP servers, commands, and a plain-file memory pipeline together. You can use it through a terminal interface (CLI), a desktop application, or a web interface. I use the CLI in this walkthrough because it sits directly alongside the project files, scripts, and Git workflow that the agent needs to work with.
Where to find OpenCode
- Website and downloads: opencode.ai and opencode.ai/download
- Documentation: opencode.ai/docs
- Source code and releases: github.com/anomalyco/opencode
Always use the official site and repository rather than third-party download mirrors.
Install the CLI
On macOS or Linux, the official OpenCode 2 installer is the quickest route:
curl -fsSL https://opencode.ai/v2/install | bash
Another documented option is the global npm package (Node.js and npm must already be installed):
npm install -g @opencode/cli
On Windows, download the standalone CLI binary for your architecture (x64 or ARM64) from the official download page, then make sure its directory is available on your PATH. The Bash installer above is intended for a Bash-compatible shell; when using WSL, run it inside your Linux distribution.
Verify that the executable is available:
opencode --version
Start OpenCode in a project
Open a terminal in the repository you want the agent to work on and run opencode:
cd /path/to/your/project
opencode
OpenCode starts its full-screen terminal interface in that directory. You can also pass the project path directly:
opencode ~/code/my-project
Choose a model
OpenCode is the interface and agent runtime; a provider supplies the model. You can start with the free model options offered by OpenCode, or connect a provider account for the models you want to use. From inside the terminal interface, run:
/connect
/models
Start in the repository root—not your home directory—so the agent has the right project context. For a first test, ask it to inspect the repository without changing anything:
Explain this repository's structure and identify its main entry points. Do not modify files.
/connect walks you through the provider's available authentication methods. Then /models lets you choose one of that provider's models. The available sign-in flow depends on the provider: it may use an API key, OAuth, or another supported method. Keep API keys out of prompts and configuration files; use the provider's authentication flow or environment variables.
Note:
This walkthrough targets the current OpenCode v2.3.0 CLI and configuration shape. The official installer above installs v2. The official migration guide documents the compatibility details.
With the CLI installed, a model selected, and OpenCode running from a project directory, the rest of this article builds the configuration around that working baseline.
Stack: OpenCode, superpowers plugin, MCP (firecrawl, apify, exa, context7, filesystem, fetch, memory, sequential-thinking), Context7, filesystem MCP.
Architecture

The setup has four conceptual layers, none of which live in the config file itself:
- Config layer — opencode.jsonc defines the runtime: model, instructions, plugins, MCP servers, formatter, LSP, permissions, timeouts.
- Agent layer — 12 subagent definitions (.md files) under ~/.config/opencode/agents/, split into 8 cheap-tier and 4 quality-tier.
- Skill/command layer — 123 skills under ~/.agents/skills/ and 16 slash commands under ~/.config/opencode/commands/.
- Memory layer — two plain-file layers: global (~/.agents/memory/) and project (/.memory/). The key insight: agent definitions, skills, and memory are file-system conventions, not config entries. That's why they work with any tool that can read a file — the config only wires the runtime to them.
Notice what is not in the config: agent definitions, skills, and memory. Those are file-system conventions, which is why they work with any tool that can read a file.
Project Layout
~/.config/opencode/
├── opencode.jsonc # the only config file
├── cli.json / service.json
├── agents/ # 12 subagent definitions (.md)
│ ├── cheap-bulk.md cheap-code.md cheap-fast.md cheap-general.md
│ ├── cheap-nano.md cheap-quality.md cheap-reason.md cheap-vision.md
│ └── code-reviewer.md planner.md security-reviewer.md tdd-guide.md
├── commands/ # 16 slash commands
└── package.json # plugin deps (superpowers)
~/.agents/
├── AGENTS.md # universal operating protocol
├── rules/CORE.md # always-on rules
├── skills/ # 123 skills
├── agents/ commands/ workflows/ templates/
├── memory/
│ ├── state.md
│ ├── topics/ decisions/ learning/ sessions/YYYY/MM/DD.md
│ └── compactions.log
├── homunculus/
│ ├── observations/YYYY-MM-DD.jsonl
│ ├── instincts/global/ instincts/projects/
│ └── aar/
└── kanban/BOARD.md
The Config File
~/.config/opencode/opencode.jsonc (paths use ~ for portability):
{
"$schema": "https://opencode.ai/config.json",
"model": "opencode-go/beam-free",
"instructions": [
"~/.agents/rules/CORE.md",
"~/.agents/AGENTS.md"
],
"plugins": ["~/.config/opencode/node_modules/superpowers"],
"mcp": {
"servers": {
"firecrawl": { "type": "remote", "url": "https://mcp.firecrawl.dev/v2/mcp-oauth" },
"apify": { "type": "remote", "url": "https://mcp.apify.com" },
"exa": { "type": "remote", "url": "https://mcp.exa.ai/mcp" },
"context7": { "type": "local", "command": ["npx", "@upstash/context7-mcp@4.5.1"],
"environment": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API}" } },
"filesystem": { "type": "local", "command": ["npx","-y","@modelcontextprotocol/server-filesystem@2.2.0","/path/to/your/projects"] },
"fetch": { "type": "local", "command": ["uvx","mcp-server-fetch==2026.11.4"] },
"memory": { "type": "local", "command": ["npx","-y","@modelcontextprotocol/server-memory@2.1.0"] },
"sequential-thinking": { "type": "local", "command": ["npx","-y","@modelcontextprotocol/server-sequential-thinking@2.1.1"] }
},
"timeout": { "startup": 30000, "catalog": 30000, "execution": 600000 }
},
"formatter": true,
"lsp": true,
"experimental": { "todo": true, "background_compaction": true },
"permissions": [
{ "action": "opencode_list_mcp_resources", "resource": "*", "effect": "allow" },
{ "action": "opencode_read_mcp_resource", "resource": "*", "effect": "allow" }
]
}
Why each block exists
| Block | Rationale |
|---|---|
instructions |
Rules live in files, so the same AGENTS.md serves OpenCode, Copilot, Codex, Gemini CLI, Cline, Cursor, Windsurf. |
model |
A free/fast default; escalate per-task instead of paying premium for git status. |
plugins |
superpowers supplies the skill system and process skills (brainstorming, systematic-debugging). |
mcp.servers |
Two classes: remote (firecrawl, apify, exa) need no install; local npx/uvx are pinned to exact versions so a surprise major bump cannot break a workflow. |
timeout.execution: 600000 |
MCP tool calls can be slow (crawls, research). A short timeout turns slow-but-working into failed. |
permissions |
Read-only MCP resource access. Writes stay behind explicit tool calls. |
Core Logic
The memory pipeline
Compaction is the event that breaks naive agent setups: the context window fills, the harness summarises, and the agent forgets the decision it made an hour ago. The fix is a deterministic file protocol, not a bigger context window.
The sequence is:
- The
PreCompacthook appends tocompactions.logand createscompaction-pending.md. - The harness compacts the context and starts a new turn.
- The agent checks whether the marker exists.
- If it does, the agent updates
state.md, appends durable topic decisions, and records a JSONL observation. - The marker is deleted only after the updates complete.
The DELETE marker step is what makes it idempotent. If the turn crashes halfway, the marker survives and the work is retried; if it completes, the marker is gone and the next turn does not redo it.
Two layers, because they answer different questions:
-
Global (
~/.agents/memory/) — who I am across projects: operating rules, decisions, learning, daily session logs. -
Project (
<repo>/.memory/) — what this repo is:index.md,state.md,topics/<topic>.md.
And one promotion rule: a pattern observed in 2+ projects gets promoted from observations to ~/.agents/homunculus/instincts/global/. That is the difference between a journal and a learning system.
Two-tier subagents
Twelve agents, split by cost:
| Tier | Agents | Use |
|---|---|---|
| Cheap (8) |
cheap-bulk, cheap-code, cheap-fast, cheap-general, cheap-nano, cheap-quality, cheap-reason, cheap-vision
|
bulk transforms, lookups, small edits, screenshot review |
| Quality (4) |
code-reviewer, planner, security-reviewer, tdd-guide
|
review, architecture, security, test-first implementation |
The routing rule is simple: route by cost, escalate by risk. A 200-file summarisation runs on cheap-bulk; an auth change goes to security-reviewer before merge. Without this split, every task uses the most expensive model and the harness becomes unusable for bulk work.
Skills are files with front-matter
A skill is a directory under ~/.agents/skills/<id>/ with a SKILL.md containing name and description. The description is not documentation — it is the trigger. OpenCode matches the task against it, so a vague description means the skill never fires.
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---
That wording is deliberate: it names the situation ("encountering a bug"), not the capability ("debugging help"). Situation-shaped descriptions fire reliably; capability-shaped ones get ignored.
Operating Workflow
- Read
state.md(global + project). - Check the kanban board.
- Invoke relevant skills before any action (1% rule: if a skill might apply, load it).
- Use Context7 for library questions — not training data.
- Research → plan → execute → verify for anything touching 3+ files.
- Update memory at the task boundary, not only at compaction.
Key Decisions
-
One
AGENTS.mdworks across every tool. Plain files, no vendor lock-in. - Plain-file memory beats a DB for cross-agent portability. Global + project layers, readable by any agent.
- Compaction is mandatory past 75% context. PreCompact hook drops a marker; the next turn updates state and deletes it.
- Skills first. If there's a 1% chance a skill applies, invoke it before acting.
- Permissions are least-privilege. Allow-listed MCP resource reads only.
-
Pin MCP versions.
@upstash/context7-mcp@4.5.1,mcp-server-fetch==2026.11.4— reproducibility over freshness.
Mistakes to Avoid
-
One tool's config everywhere. One
AGENTS.mdworks across VS Code, Copilot, OpenCode, Codex, Gemini CLI, Cline, Cursor, Windsurf. - Forgetting compaction duty. Past 75% context, compact or stop.
- Exposing credentials. Never in prompts, outputs, or logs. Validate input; least privilege.
-
Unpinned MCP servers. A
latesttag eventually breaks a workflow mid-task. - Overloaded main context. Subagents keep exploration out of the parent window.
- Memory as an afterthought. If it is not written at a boundary, it is lost at compaction.
Checklist
- [ ] Create
~/.config/opencode/opencode.jsoncwith$schema,model,instructions,plugins. - [ ] Put cross-tool rules in
~/.agents/AGENTS.md+~/.agents/rules/CORE.md; reference them frominstructions. - [ ] Add MCP servers: remote first (no install), local second — with pinned versions and explicit timeouts.
- [ ] Set
permissionsto read-only for MCP resources. - [ ] Write 8 cheap-tier and 4 quality-tier agent files under
~/.config/opencode/agents/. - [ ] Install skills under
~/.agents/skills/; give every one a situation-shapeddescription. - [ ] Add 16 commands under
~/.config/opencode/commands/. - [ ] Create
~/.agents/memory/{state.md,topics,decisions,learning,sessions}and<repo>/.memory/{index,state,topics}. - [ ] Wire hooks:
PreCompact(appendcompactions.log+ drop marker),SessionStart(read state),Stop(write state). - [ ] Implement the 6-step compaction duty and delete the marker last.
- [ ] Add a promotion rule: observation seen in 2+ projects →
homunculus/instincts/global/. - [ ] Keep
~/.agents/kanban/BOARD.mdand update task status as you work.
Quick Start
- Install OpenCode.
- Create
~/.config/opencode/opencode.jsonc(see above). - Place
~/.agents/rules/CORE.mdand~/.agents/AGENTS.md. - Install skills under
~/.agents/skills/and subagents under~/.config/opencode/agents/. - Wire MCP servers; verify with
opencode_list_mcp_resources. - Add hooks: PreCompact, SessionStart, Stop.
Verification
- Subagents: 12 (8 cheap tier + 4 quality tier).
- Skills: 123 installed.
- Commands: 16.
- MCP servers: 8.
- Hook check: trigger a compaction, confirm
compactions.loggrows andcompaction-pending.mdappears. - Duty check: on the next turn, confirm
state.mdis updated and the marker is gone. - Secrets check: grep the config for literal keys — every credential should be
{env:…}.
Takeaway
The engineering philosophy behind this setup comes down to a handful of principles:
Separation of concerns across three layers. Configuration defines the runtime (opencode.jsonc), reusable files define how agents work (skills, subagents, commands), and plain-file memory carries context between sessions. None of these layers depends on the others' internals, so you can change one without breaking the rest.
Plain files beat databases for agent portability. Everything is Markdown, JSON, or JSONL — readable by any tool that can read a file. The same AGENTS.md serves OpenCode, Copilot, Codex, Gemini CLI, Cline, Cursor, and Windsurf. No proprietary format, no vendor lock-in, no migration path to worry about.
Compaction is inevitable — design for it, don't fight it. Context windows fill up. Instead of hoping for a bigger window, the setup uses a deterministic file protocol: a PreCompact hook drops a marker, the next turn updates state and deletes the marker last. If a turn crashes halfway, the marker survives and the work retries. Idempotency over optimism.
Route by cost, escalate by risk. Eight cheap subagents for bulk transforms and lookups, four quality subagents for review, architecture, and security. A 200-file summarization runs on cheap-bulk; an auth change goes to security-reviewer before merge. Without this split, every task uses the most expensive model and bulk work becomes unusable.
Memory is a learning system, not a journal. Two layers answer different questions — global (who I am across projects) and project (what this repo is). A pattern observed in 2+ projects gets promoted from observations to global instincts. That promotion rule is what separates accumulation from learning.
Skills are triggers, not documentation. A skill's description names the situation ("encountering a bug"), not the capability ("debugging help"). Situation-shaped descriptions fire reliably; capability-shaped ones get ignored. And the 1% rule — if there's even a 1% chance a skill applies, invoke it before acting.
Least privilege and reproducibility. Permissions allow-list MCP resource reads only; writes stay behind explicit tool calls. MCP servers are pinned to exact versions (@upstash/context7-mcp@4.5.1) so a surprise major bump can't break a workflow mid-task. Remote servers first (no install), local second.
Subagents keep the parent context clean. Exploration happens in child sessions so the parent window stays focused on the actual task. The harness becomes unusable if every file read pollutes the main context.




Top comments (0)