Building AI agents: OpenCode and Claude Code in one repo

Agent vs chatbot

A chatbot answers; an agent acts. The difference is the loop: the agent reads the goal, picks a tool, observes the result, and repeats until the goal is done or it gets stuck and asks for help. If your system cannot call tools and see results, it is a chatbot with good marketing.

This page is tool-agnostic: the roles and the operating rules work the same in OpenCode and Claude Code. The exact file formats and frontmatter live in the dedicated guides: OpenCode agents and Claude Code subagents. Read this page for the why, then open the guide for the tool you use.

Same roles, two tools

Both tools converged on the same four roles: a cheap triage that reads and routes, a builder that edits and tests, a read-only reviewer that judges the diff, and an orchestrator that fans work out to children. Only the file names differ:

The roles map to the model split used across this section: the free OpenCode model for triage, GPT 6 Luna for building, Claude Opus 5.5 for review. Cheap reads, standard builds, expensive verdicts.

Share skills, split agents

Skills are the portable half. They follow the Agent Skills open standard, and OpenCode also reads .claude/skills/ as a compatibility location — so that directory is the one place both assistants load the same procedures. Agents are the local half: agent files name tools and models in tool-specific formats, so they stay separate.

repo/ ├── AGENTS.md shared instructions ├── .claude/skills/ read by OpenCode and Claude Code │ ├── api-review/SKILL.md │ └── test-writer/SKILL.md ├── .opencode/agents/ OpenCode roles │ ├── triage.md │ ├── builder.md │ └── reviewer.md └── .claude/agents/ Claude Code roles ├── code-reviewer.md └── test-runner.md

• Instructions: keep one committed AGENTS.md. OpenCode reads only that file. Claude Code reads it when no CLAUDE.md exists, so either avoid a CLAUDE.md or make it a one-line @AGENTS.md import.
• Skills: author once under .claude/skills/. OpenCode picks it up; Claude Code treats it as native.
• Agents: duplicate the role definitions per tool, not the prose. Keep the same names (triage, builder, reviewer) so the workflow reads the same in both.
• Permissions: grant each role the same rights in both tools: triage cannot edit or run shell, builder cannot push, reviewer can only read.

A combined workflow

Run two assistants on one repo when the roles genuinely differ, not to double the noise. A pattern that pays off:

• 1. Triage cheap. Start the day in the cheaper tool: With triage, explain the failing checkout flow and route the fix to builder or plan. Read-only, no edits, no risk.
• 2. Build in the tuned tool. The repo with the richest OpenCode config builds there: With builder, add retry handling to the payment client and cover it with test-writer. Builder edits and runs the narrow tests.
• 3. Review in the other tool. Switch to Claude Code and call the read-only reviewer: Use the code-reviewer subagent on my staged changes. A different model with a different prompt catches what the builder normalized away.
• 4. Fix and re-verify. Apply the findings in the builder session, then ask the reviewer for a verdict on the new diff. Two passes is normal; three means the task was under-specified.

Handoff happens through files, not chat: commit decisions to AGENTS.md, plans and tasks to markdown, and let each tool read its own session history. Do not edit the same file in two sessions at once; when parallel edits are unavoidable, use worktree isolation in Claude Code or a separate checkout in OpenCode. And skip the ceremony for small fixes: one agent plus a good skill beats a two-tool pipeline.

Make the agents run

A correct agent file does nothing by itself. Two more things must happen: the assistant has to load the project config, and a person or command has to select the role. Most tickets titled "agents created, agents unused" are one of those two — or a model id that stopped resolving.

• 1. Start where the config lives. Both tools discover instructions and agents per project directory: OpenCode from opencode.jsonc and .opencode/agents/, Claude Code from CLAUDE.md (or AGENTS.md) and .claude/agents/. A session started in a home directory or a sibling checkout sees none of them and runs the built-ins.
• 2. Make every model id resolve. OpenCode wants provider/model plus the variant; Claude Code accepts aliases, full ids or inherit. A stale id falls back to the session model or refuses to start, and an allowlist can substitute the model with only a warning.
• 3. Select the role per task. OpenCode has a picker and default_agent; Claude Code delegates to subagents by description or on request. Defining a role never makes it the default.
• 4. Give every role a canary task. Triage explains one flow and names the next agent; builder makes one small edit and shows the diff; reviewer finds one planted bug in a staged diff; orchestrator returns two child results. One pass-fail line per role beats a page of config.
• 5. Read the history, not the folder. OpenCode records the agent and model per session; Claude Code lists running subagents and their model with /tasks. A role that never appears in the history is decoration.
• 6. Batch only independent work. Parallel children are the real win: five read-only checks or five lesson drafts at once. A one-line edit is not: the spawn costs more than the task.

Permissions are the trap that looks like a broken model: rules are ordered and the last match wins, and an agent denied the one tool its job needs answers with an apology instead of an error. Re-read the rules before the first eval.

From demo to production

Demos survive on the happy path; production is everything else. Graduate in this order, with a concrete gate per step:

• 1. Sandbox side effects: builder asks for shell, denies push. Run git diff --stat before every commit.
• 2. Human approval: migration and deploy skills show the diff and wait. A question tool asks before breaking APIs.
• 3. Persist memory: commit AGENTS.md, skills and agents so a restart reloads the same guidance.
• 4. Measure per task: track success on triage, build and review separately. Fix the worst role first — often triggers, not the model.

Repeat until the numbers, not impressions, say it is ready. Keep one working setup until the new behavior is verified; changing instructions mid-flight makes every measurement meaningless.

Memory that survives restarts

Short-term memory (the running trace) dies with the process; decisions must land in files to survive. Keep three stores: global user rules, repo-root rules in AGENTS.md for both tools, and nested files for areas that need their own rules. Claude Code can layer a CLAUDE.md on top and keeps its own auto memory; OpenCode reloads the shared files on start.

# AGENTS.md - Run the narrowest test before every commit. - Keep database queries in src/database. - Do not edit generated files directly.

Keep the root file short and verifiable; a procedure that outgrows it belongs in a skill. Edits to instruction files apply before the next request in both tools; newly added nested files load on demand when work reaches that directory.

Evals before opinions

Ten fixed tasks with checkable outcomes beat a hundred demo impressions. Starter suite for the four roles, run in both tools:

• Triage x3: explain a login flow, route a docs fix vs a feature, refuse a secrets task. Must not edit.
• Builder x3: add validation with tests green, rename across two files, keep a public API stable.
• Reviewer x2: catch a missing 401 on an expired token, demand a test for replay. Must not edit.
• Orchestrator x2: plan pagination in three bullets, fan out and merge three child results.

Run the suite on every prompt, tool or model change and keep the history: a two-point drop after an improvement is the norm, not the exception. Try the same suite on the free OpenCode model, Luna and Opus once — the gap tells you which role deserves the expensive model.

Detailed guides per tool

• OpenCode: download, install and use — configuration, models, workflows.
• OpenCode agents — agent files, frontmatter, four complete examples, commands.
• Claude Code: install, configure and use — memory, permissions, skills, MCP servers.
• Claude Code subagents — every frontmatter field, tool limits, five examples, evals.
• Writing skills for AI assistants — the portable half both tools share.
• Models for coding agents — which model per role, with ids.
• Researcher agent and Analyst agent — two OpenCode worked examples.
• Claude Code, OpenCode and a human in one repository — a worktree and a branch per agent, review and merge by a person.
• Three-tier agents in VS Code — GitHub Copilot custom agents on Claude Opus 5.5, Claude Haiku 5.5 and GPT-6 Luna.

Article author: Arthur Isaev