Agentic development uses autonomous AI agents to plan, code, test, and fix software with reasoning loops and tools, while developers focus more on guiding and reviewing workflows. The first step to orchestrate it effectively is to set up a customized AI coding harness.
Many Coding harnesses are there currently: Claude Code, Cursor, OpenAI Codex, Google Antigravity, Kiro, OpenCode.
However, many solo developers, and development teams waste countless hours trying to fight their way out of AI slop created by the harnesses.
Why? Because they haven’t customized the harness to their specific domain or use case. They give the AI full access, type a prompt, and hope it doesn’t break their architecture.
In this guide, I will walk you through unlocking the true potential of **OpenCode — **a rapidly growing, open-source coding harness that you can plug in any LLM and even self-host the infrastructure.
TL;DR:I have already packaged this entire setup and the architecture into a cloneable GutHub repo. You can grab the detailed steps, baseline config, subagents, and AGENTS.md right now on GitHub: 👉[.]Clone the Opencode-Harness Template here
Read on for the step-by-step breakdown of how and why this architecture works.
OpenCode is an open-source AI coding agent. It runs in your terminal, IDE, or desktop. It supports 75+ providers (Anthropic, OpenAI, OpenRouter, local models), allows you to plug in external tools via MCP (Model Context Protocol) servers, and lets you define custom agents, skills, and rules.
For most users, the simplest way to install OpenCode is via npm or the install script.
macOS / Linux:
curl -fsSL https://opencode.ai/install | bash
Windows (via npm):
npm install -g opencode-ai
(Note: If you use other package managers like Homebrew, Arch, or Chocolatey, check the official OpenCode documentation for specific commands).
Open OpenCode in any project directory by typing opencode in your terminal. Inside the TUI, run:
/connect
Select your provider (e.g., Anthropic, OpenAI, OpenRouter, or OpenCode Zen). If you are setting environment variables manually, OpenCode reads them from the OS environment, **not from **.env files. Set them once at the user level so they're available to every terminal.
Windows PowerShell (Pro-tip to permanently load a .env file):
Get-Content .env | Where-Object { $_ -match '^\s*[^#]\w+=.+' } | ForEach-Object { $k,$v = $_ -split '=',2 [System.Environment]::SetEnvironmentVariable($k.Trim(), $v.Trim(), 'User')}
Linux/macOS: Add export GITHUB_TOKEN=ghp_... to your ~/.zshrc or ~/.bashrc.
OpenCode merges configurations from multiple locations. Later sources override earlier ones for conflicting keys, but non-conflicting keys are merged together.
Precedence order (Lowest to Highest):
Key insight: They merge, they don’t replace. If your global config sets "autoupdate": true and your project sets a specific model, both apply.
Navigate to your project folder, start opencode, and type /init.
OpenCode will scan your project and create an AGENTS.md file. This rules file is automatically loaded into every session, providing the agent with your build commands, repo structure, and project-specific gotchas.
AGENTS.md is the most important file in your harness. It dictates what the project is, the architecture principles, and what the agent should never do.
Where OpenCode looks for rules (in order of precedence):
What makes a good AGENTS.md:
You might have dense reference files (like API standards) that you don’t want burning tokens unless strictly necessary. You can explicitly instruct the LLM to fetch them using its read tool:
## External File CRITICAL: When you encounter a file reference (e.g., @docs/general.md), use your Read tool to load it on a need-to-know basis. - Do NOT preemptively load all references - use lazy based on actual need.## Development Guidelines- For React component architecture: @docs/react-patterns.md- For REST API design: @docs/api-standards.md
MCP (Model Context Protocol) servers give OpenCode access to external tools like GitHub, Supabase, and Cloudflare.
Important:Every enabled MCP server adds tokens to your context window. Disable heavy servers (like GitHub) globally and enable them per-agent.
Here is how to configure them in your opencode.jsonc:
{ "mcp": { // Context7: Free doc search (No API key needed) "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "enabled": true }, // Grep by Vercel: Search GitHub code examples "gh_grep": { "type": "remote", "url": "https://mcp.grep.app", "enabled": true }, // GitHub: Repo management (Requires token) "github": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-github"], "environment": { "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}" }, "enabled": false // Change to true when needed } }}
OpenCode ships with five built-in agents. You don’t need custom agents for a generic CRUD app, but you do need them for domain-specific logic, scoped permissions, or independent analysis.
Built-in Agents:
When to create Custom Agents:
Agent Definition Example (****.opencode/agents/security-auditor.md):
---description: "Run security audit on current changes"mode: subagent model: opencode-go/minimax-m3temperature: 0.1 steps: 25 permission: edit: deny bash: deny---Use this agent to review all files changed since the last git commit. Focus specifically on data-at-rest risks and authentication flaws.
Skills are reusable knowledge chunks stored in SKILL.md files. Unlike AGENTS.md (which is always loaded), skills are loaded on demand.
Think of skills as your project’s reference library — database schemas, API contracts, grading rubrics, or ingredient lists.
File Structure:
.opencode/└── skills/ └── db-schema/ └── SKILL.md (Must be uppercase)
How skills are loaded:
OpenCode features a granular permission system. Most permissions default to "allow", but doom_loop (repeating the same broken tool call) and external_directory default to "ask". .env files are hard-blocked from being read by default.
Only configure what you want to restrict. The best practice is setting bash commands to "ask":
{ "agent": { "build": { "permission": { "bash": { "*": "ask", "git status*": "allow", "git log*": "allow", "npm run*": "allow" } } } }}
Keep machine-specific settings out of your shared repository!
A well-structured opencode.jsonc is minimal, commented, and strictly separates machine-specific settings from shared team settings. Rely on {env:VAR} for all secrets, disable heavy MCP servers by default, and commit it to source control.
Here is the recommended generic template layout for your project repository:
your-project/│├── opencode.jsonc # Config: model, MCP, permissions├── AGENTS.md # Project rules loaded automatically├── .env.example # Env var placeholders│├── docs/│ ├── design/ # Architecture docs│ └── knowledge/ # Reference material│└── .opencode/ ├── agents/ │ ├── domain-expert.md # Domain rules, read-only │ └── security-auditor.md# OWASP review, read-only │ └── skills/ ├── db-schema/ │ └── SKILL.md # SQL schema and RLS policies └── module-contracts/ └── SKILL.md # API contracts
If you want to implement this architecture, you don’t have to build it from scratch.
I’ve packaged this exact architecture into a detailed guide with a production-ready template repository. It includes the safe opencode.jsonc defaults, the AGENTS.md skeleton, and the sample @security-auditor subagent for reference.
Start building in 15 minutes:
👉https://github.com/sac34333/Opencode-Harness
How to Build a Production-Ready AI Agent Harness with OpenCode was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.