{"slug": "how-to-build-a-production-ready-ai-agent-harness-with-opencode", "title": "How to Build a Production-Ready AI Agent Harness with OpenCode", "summary": "OpenCode, an open-source AI coding harness that supports 75+ providers and custom agents, skills, and rules, offers a production-ready setup for agentic development, according to a guide by an unnamed author. The guide emphasizes customizing the harness with an AGENTS.md file and configuration merging to avoid 'AI slop' and improve workflow efficiency. It provides installation steps for macOS, Linux, and Windows, and highlights the importance of setting environment variables at the user level.", "body_md": "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.\n\nMany Coding harnesses are there currently: Claude Code, Cursor, OpenAI Codex, Google Antigravity, Kiro, OpenCode.\n\nHowever, many solo developers, and development teams waste countless hours trying to fight their way out of AI slop created by the harnesses.\n\nWhy? 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.\n\nIn 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.\n\nTL;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\n\n*Read on for the step-by-step breakdown of how and why this architecture works.*\n\nOpenCode 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.\n\nFor most users, the simplest way to install OpenCode is via npm or the install script.\n\n**macOS / Linux:**\n\n```\ncurl -fsSL https://opencode.ai/install | bash\n```\n\n**Windows (via npm):**\n\n```\nnpm install -g opencode-ai\n```\n\n(Note: If you use other package managers like Homebrew, Arch, or Chocolatey, check the [official OpenCode documentation](https://opencode.ai/docs/#install) for specific commands).\n\nOpen OpenCode in any project directory by typing opencode in your terminal. Inside the TUI, run:\n\n```\n/connect\n```\n\nSelect 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.\n\n**Windows PowerShell (Pro-tip to permanently load a .env file):**\n\n```\nGet-Content .env | Where-Object { $_ -match '^\\s*[^#]\\w+=.+' } | ForEach-Object {    $k,$v = $_ -split '=',2    [System.Environment]::SetEnvironmentVariable($k.Trim(), $v.Trim(), 'User')}\n```\n\n**Linux/macOS:** Add export GITHUB_TOKEN=ghp_... to your ~/.zshrc or ~/.bashrc.\n\nOpenCode merges configurations from multiple locations. Later sources override earlier ones for conflicting keys, but non-conflicting keys are merged together.\n\n**Precedence order (Lowest to Highest):**\n\n**Key insight:** They merge, they don’t replace. If your global config sets \"autoupdate\": true and your project sets a specific model, both apply.\n\nNavigate to your project folder, start opencode, and type /init.\n\nOpenCode 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.\n\nAGENTS.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.\n\n**Where OpenCode looks for rules (in order of precedence):**\n\n**What makes a good AGENTS.md:**\n\nYou 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:\n\n```\n## External File LoadingCRITICAL: 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 loading based on actual need.## Development Guidelines- For React component architecture: @docs/react-patterns.md- For REST API design: @docs/api-standards.md\n```\n\nMCP (Model Context Protocol) servers give OpenCode access to external tools like GitHub, Supabase, and Cloudflare.\n\nImportant:Every enabled MCP server adds tokens to your context window. Disable heavy servers (like GitHub) globally and enable them per-agent.\n\nHere is how to configure them in your opencode.jsonc:\n\n```\n{  \"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    }  }}\n```\n\nOpenCode 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.\n\n**Built-in Agents:**\n\n**When to create Custom Agents:**\n\n**Agent Definition Example (****.opencode/agents/security-auditor.md):**\n\n```\n---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.\n```\n\nSkills are reusable knowledge chunks stored in SKILL.md files. Unlike AGENTS.md (which is always loaded), skills are loaded **on demand**.\n\nThink of skills as your project’s reference library — database schemas, API contracts, grading rubrics, or ingredient lists.\n\n**File Structure:**\n\n```\n.opencode/└── skills/    └── db-schema/        └── SKILL.md  (Must be uppercase)\n```\n\n**How skills are loaded:**\n\nOpenCode 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.\n\nOnly configure what you want to restrict. The best practice is setting bash commands to \"ask\":\n\n```\n{  \"agent\": {    \"build\": {      \"permission\": {        \"bash\": {          \"*\": \"ask\",          \"git status*\": \"allow\",          \"git log*\": \"allow\",          \"npm run*\": \"allow\"        }      }    }  }}\n```\n\nKeep machine-specific settings out of your shared repository!\n\nA 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.\n\nHere is the recommended generic template layout for your project repository:\n\n```\nyour-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\n```\n\nIf you want to implement this architecture, you don’t have to build it from scratch.\n\nI’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.\n\n**Start building in 15 minutes:**\n\n👉[https://github.com/sac34333/Opencode-Harness](https://github.com/sac34333/Opencode-Harness)\n\n[How to Build a Production-Ready AI Agent Harness with OpenCode](https://pub.towardsai.net/how-to-build-a-production-ready-ai-agent-harness-with-opencode-483c019e66d9) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/how-to-build-a-production-ready-ai-agent-harness-with-opencode", "canonical_source": "https://pub.towardsai.net/how-to-build-a-production-ready-ai-agent-harness-with-opencode-483c019e66d9?source=rss----98111c9905da---4", "published_at": "2026-09-04 05:47:36+00:00", "updated_at": "2026-09-04 06:22:05.382995+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["OpenCode", "Anthropic", "OpenAI", "OpenRouter", "OpenCode Zen", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/how-to-build-a-production-ready-ai-agent-harness-with-opencode", "markdown": "https://wpnews.pro/news/how-to-build-a-production-ready-ai-agent-harness-with-opencode.md", "text": "https://wpnews.pro/news/how-to-build-a-production-ready-ai-agent-harness-with-opencode.txt", "jsonld": "https://wpnews.pro/news/how-to-build-a-production-ready-ai-agent-harness-with-opencode.jsonld"}}