Agent Harnesses: Claude Code, OpenCode, T3 Code, Codex
Applies to: every engineer starting on a client engagement · Time to learn: 30 min reading + 15 min exercise · Lever: context, feedback, and guardrails (the harness carries all three)
The model is only part of what you use. The program around it, the harness, decides which tools the model can call, how permissions work, and how context is managed. This page compares the main harnesses (as of 2026-10), explains OpenCode and T3 Code, and shows how to set up a repo so you can switch harness without rewriting anything.
- A harness is model + tools + loop + permissions + context management. Two harnesses with the same model can behave very differently.
- T3 Code is not a harness itself: it is a GUI that runs harnesses such as Claude Code and Codex.
- Stay harness-agnostic:
AGENTS.mdas the source of truth, skills in the openSKILL.mdformat, MCP servers configured per tool. - On a client engagement, start from constraints: data residency, approved providers, and whether local models are required. OpenCode can use local models.
- For scripts and CI, use the headless mode of your harness (
claude -p,opencode run).
Why it matters in the AI age
Clients differ. One approves only a single cloud provider, another requires models inside its own network, a third has no policy yet. If your team knowledge lives in one tool's private format, you start over each time. If it lives in open formats (AGENTS.md, SKILL.md, MCP), you carry it from client to client and from tool to tool.
Core concepts
What a harness is
| Part | What it does | Example |
|---|---|---|
| Model | Decides the next step | Claude, GPT, a local model |
| Tools | Read and edit files, run commands, call MCP servers | Bash, Edit, MCP tools |
| Loop | Calls the model, runs the tools, feeds results back | Until done or you stop it |
| Permissions | Decide what runs without asking | Claude Code: allow, ask, deny rules |
| Context management | Loads instructions, compacts or clears history | /clear, /compact, subagents |
Anthropic's harness-design post makes the key point: every harness component encodes an assumption about what the model cannot do alone, so harnesses change as models improve.
Comparison (as of 2026-10)
| Harness | What it is | License | Providers | Project instructions | Install |
|---|---|---|---|---|---|
| Claude Code | Terminal CLI, IDE extensions, desktop app, web; one engine for all | Proprietary | Anthropic models (see the docs for cloud routes) | CLAUDE.md; reads AGENTS.md when no CLAUDE.md exists; @AGENTS.md import works everywhere | curl -fsSL https://claude.ai/install.sh | bash |
| OpenCode | Open-source terminal agent, with desktop app (beta) and IDE extension | MIT | 75+ providers, custom OpenAI-compatible endpoints, local models | AGENTS.md; falls back to CLAUDE.md | see below |
| Codex CLI | OpenAI's open-source terminal agent | Apache-2.0 | OpenAI | AGENTS.md, discovered from the repo root down to the current directory | npm install -g @openai/codex |
| T3 Code | GUI that runs other harnesses | MIT | Whatever the installed harness uses | Whatever the harness uses | see below |
One-liners for other tools you will meet:
- Cursor (editor and CLI agent): terminal agent with interactive and print modes and Agent, Plan, and Ask modes; reads
AGENTS.mdin the root and subdirectories. - GitHub Copilot cloud agent: runs in an ephemeral cloud environment, works in the background, creates branches and pull requests; reads
AGENTS.md,CLAUDE.md, andGEMINI.md. - Gemini CLI: open-source terminal agent for Gemini models (Apache-2.0); reads
GEMINI.mdby default and readsAGENTS.mdonly if you list it undercontext.fileNamein its settings.
OpenCode
OpenCode is an open-source (MIT) coding agent for the terminal with a desktop app (beta) and an IDE extension. Repo: anomalyco/opencode.
| Topic | Detail |
|---|---|
| Providers | The docs list "75+ LLM providers" including Anthropic, OpenAI, Amazon Bedrock, Google Vertex AI, GitHub Copilot, OpenRouter, and Ollama. Custom OpenAI-compatible providers are supported. |
| Config | opencode.json or opencode.jsonc in the project root; global file at ~/.config/opencode/opencode.json; OPENCODE_CONFIG sets a custom path |
| Agents | build (default, full access), plan (read-only, asks before bash), general (subagent, call with @general); switch with Tab |
| Instructions | AGENTS.md at the project root or ~/.config/opencode/AGENTS.md; /init creates it; an instructions array accepts paths and globs |
| Claude Code fallback | Reads CLAUDE.md when no AGENTS.md exists; disable with OPENCODE_DISABLE_CLAUDE_CODE=1 |
| MCP | Configured under the mcp key, local or remote |
| Plugins | plugin option (npm packages) or files in .opencode/plugins/ |
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"instructions": ["AGENTS.md"]
}
To use a local or self-hosted model, run /connect, choose "Other", then add a provider entry with options.baseURL and models in opencode.json, and check it with /models. This is what makes OpenCode the usual choice when a client requires models inside its own network (see the Agentic AI Platforms page for serving options).
T3 Code
T3 Code (repo: https://github.com/pingdotgg/t3code) is, in the repo's words, "the open-source control plane for coding agents." It does not replace Claude Code or Codex. It is a GUI that runs them on your machine, so install and sign in to each harness first. Available as a web app, desktop app, and mobile apps. License: MIT.
| Capability | What it gives you |
|---|---|
| Threads | Each thread can be bound to its own git worktree and branch, so parallel tasks do not collide |
| Delegation | An agent in a thread can delegate child tasks to other providers and models and track them |
| Pull requests | Links and watches pull requests from a thread |
| Scheduling | Schedules recurring or webhook-triggered agent tasks |
| Previews | Renders HTML previews and can drive a browser preview |
The T3 Code README says the project is "very very early" and to "expect bugs." Use it for non-critical work first, and keep your repo setup independent of it (the next section shows how).
How to do it
1. Make AGENTS.md the source of truth
AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation; the agents.md site lists Codex, OpenCode, Cursor, Copilot, and many others as supporters. Details of what goes in it are on AGENTS.md, CLAUDE.md, and Rules.
For Claude Code, add a CLAUDE.md that imports it:
@AGENTS.md
## Claude Code
- Use plan mode for changes that touch more than one module.
A symlink (ln -s AGENTS.md CLAUDE.md) also works, but the Claude Code docs note that Edit and Write refuse to write through it and Windows checkouts can break it. Prefer the import.
Claude Code reads AGENTS.md natively only when no CLAUDE.md exists in the working directory or above, and only CLAUDE.md is read if one exists. Do not rely on native reading in a repo that already has a CLAUDE.md.
2. Write skills in the open format
A skill is a folder with a SKILL.md that has YAML frontmatter with name and description. Claude Code reads .claude/skills/<name>/SKILL.md; Codex reads .agents/skills. Keep one source and link it into each location. See Skills and Skill Creation.
mkdir -p .agents/skills .claude/skills
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes
3. Configure MCP per tool
MCP is an open protocol, but each harness has its own config file. Keep one short list of servers in AGENTS.md and translate it.
| Harness | Where MCP servers are configured |
|---|---|
| Claude Code | .mcp.json (project, shared), ~/.claude.json (local and user scopes) |
| OpenCode | mcp key in opencode.json |
| Codex | ~/.codex/config.toml (check the Codex docs for the MCP table syntax) |
Which servers to add, and how many, is covered in MCP Servers.
4. Install
curl -fsSL https://claude.ai/install.sh | bash
# or: brew install --cask claude-code
curl -fsSL https://opencode.ai/v2/install | bash
# or: brew install opencode, or: mise use -g opencode
npm install -g @openai/codex
# or: brew install --cask codex
curl -fsSL https://t3.codes/install.sh | sh # macOS and Linux
npx t3@latest # try without installing
t3 # start the server and open the web app
Sign in with claude auth login, codex login, or opencode auth. OpenCode's docs mention both an OpenCode 1 and an OpenCode 2 install path and warn that mixing them can conflict, so use one method per machine.
5. Headless and CI mode
| Harness | Command | Notes |
|---|---|---|
| Claude Code | claude -p "..." | Works with pipes: tail -200 app.log | claude -p "explain the errors". The Agent SDK is the programmatic route. |
| OpenCode | opencode run "..." | --format json returns raw events; --model provider/model; --auto auto-approves permissions not explicitly denied. opencode serve plus --attach avoids MCP cold-start on each run. |
| Codex | see the Codex documentation | Non-interactive usage was not verified for this page |
In CI, give a headless agent the same guardrails as a human: a read-only or tightly scoped permission set, no production credentials, and the repo's normal gates after it finishes. See Hooks, Pre-commit, and Quality Gates.
6. Choose a harness for an engagement
| Question to ask the client | If the answer is... | Then |
|---|---|---|
| Which model providers are approved? | One cloud provider (for example Bedrock or Vertex AI) | Pick a harness that supports it: Claude Code and OpenCode both list these providers; confirm in current docs |
| Where may code and prompts go? | Must stay inside the network | OpenCode with a local or self-hosted OpenAI-compatible endpoint |
| Is a managed policy needed? | Yes, for permissions and settings | Claude Code supports managed settings that take precedence over user and project settings |
| Can we install tools on laptops? | No | Use the client's approved IDE or the cloud agent they already license |
| Are several agents in parallel useful? | Yes | A GUI such as T3 Code, or git worktrees in any harness (see Execution Plans) |
Ask these questions in the first week and record the answers in the repo's AGENTS.md or a short decision note.
Best practices
- Put commands, conventions, and gotchas in
AGENTS.mdand keep tool-specific settings in tool-specific files. - Commit shared settings (
.claude/settings.json,.mcp.json,opencode.json); keep personal ones gitignored. - Use the same lint, test, and build commands in every harness; define them once in
mise.tomltasks (see The Agent-Ready Toolchain). - Re-evaluate your harness choice every few months; this area moves quickly.
Pitfalls to design around
- Write instructions once. If you maintain
AGENTS.mdand a full copy inCLAUDE.md, they drift; import instead. - Check each harness's discovery rules. Claude Code skips
AGENTS.mdwhen aCLAUDE.mdorCLAUDE.local.mdis present; Codex stops adding instruction files at its size limit (32 KiB by default per its docs). - Treat third-party skills and MCP servers as code you install: read them first, and pin versions.
- Install the CLI harness before asking a GUI such as T3 Code to use it; the GUI runs the harness, it does not replace it.
Try it
Lab 15 minutes on a real repo
- Create or trim
AGENTS.mdto the build, test, and lint commands plus five conventions. - Add
CLAUDE.mdcontaining@AGENTS.md. - Start Claude Code and ask "What commands test this project?" Then start OpenCode in the same repo and ask the same question. Both should answer from
AGENTS.md. - Run one headless command in each:
claude -p "list the test commands"andopencode run "list the test commands". - Write down which harness fits your current client and why, using the table above.
Checklist
-
AGENTS.mdexists and is the single source of project instructions. -
CLAUDE.mdimportsAGENTS.md(or the repo has noCLAUDE.md). - Skills live in one folder and are linked for each harness in use.
- MCP servers are listed once and configured per tool, pinned and least-privilege.
- I know the client's approved providers and data-residency rules.
- A headless command works in my chosen harness.
Sources
- Claude Code overview (surfaces, install,
-p): https://code.claude.com/docs/en/overview - Claude Code memory (AGENTS.md handling, imports, symlink caveat): https://code.claude.com/docs/en/memory
- Claude Code settings and managed policy: https://code.claude.com/docs/en/settings
- Claude Code MCP scopes: https://code.claude.com/docs/en/mcp
- OpenCode docs: https://opencode.ai/docs/ , providers https://opencode.ai/docs/providers/ , config https://opencode.ai/docs/config/ , rules https://opencode.ai/docs/rules/ , CLI https://opencode.ai/docs/cli/
- OpenCode repo (MIT, agents, install commands): https://github.com/anomalyco/opencode
- Codex CLI repo (Apache-2.0, install): https://github.com/openai/codex
- Codex AGENTS.md discovery: https://learn.chatgpt.com/docs/agent-configuration/agents-md
- Codex skills: https://learn.chatgpt.com/docs/build-skills
- Codex config: https://learn.chatgpt.com/docs/config-file/config-basic
- T3 Code repo and site: https://github.com/pingdotgg/t3code , https://t3.codes
- AGENTS.md: https://agents.md/ and https://aaif.io/news/linux-foundation-announces-formation-of-aaif
- Cursor rules and CLI: https://cursor.com/docs/context/rules , https://cursor.com/docs/cli/overview
- GitHub Copilot cloud agent: https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent , https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
- Gemini CLI: https://github.com/google-gemini/gemini-cli and https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md
- Harness design for long-running apps: https://www.anthropic.com/engineering/harness-design-long-running-apps