AGENTS.md for OpenCode: Complete Setup Guide for the Open-Source Terminal Agent (2026)

OpenCode has crossed 160,000 GitHub stars and its AGENTS.md support is the feature that catches most Claude Code migrants off guard: the file you already have works immediately, with zero modification.

That compatibility is intentional, but the details matter. OpenCode’s discovery order, its opencode.json instructions field, and its /init auto-generation command give you more configuration surface than AGENTS.md alone. This guide covers all of it — from the first file placement to advanced glob patterns and the differences between Build and Plan mode.

What is OpenCode and Why AGENTS.md Matters

OpenCode is a terminal-based, open-source AI coding agent. Unlike closed tools that lock you into a single model, OpenCode supports multiple LLM backends from a single installation: Claude (via Anthropic API), GPT-4 (OpenAI), Gemini (Google), and local models via Ollama or compatible endpoints.

The 160K+ star count reflects that appeal. Developers who want Claude-quality output but need the flexibility to switch providers — or run models locally for privacy — have made OpenCode a primary tool.

AGENTS.md matters here for two reasons:

Cross-tool compatibility. If your repository already has an AGENTS.md (or CLAUDE.md), OpenCode reads it without additional setup. Teams using mixed tooling — some members on Claude Code, some on OpenCode — share a single instruction file.

Backend-agnostic rules. Because OpenCode routes to different LLMs, your AGENTS.md becomes the stable contract across backends. The rules you write for Claude sessions also apply when the same developer switches to GPT-4 in the same project.

How OpenCode Reads AGENTS.md — Discovery Order

OpenCode follows a defined priority chain when loading instructions:

1. Project root AGENTS.md

OpenCode first looks for AGENTS.md at the Git repository root. This is the primary project-level configuration. If you have only one AGENTS.md, this is where it goes.

2. ~/.config/opencode/AGENTS.md (global)

For personal preferences that apply across all projects — preferred code style, commit message format, tools to never use — create a global AGENTS.md at ~/.config/opencode/AGENTS.md. OpenCode merges this with the project-level file, with project-level rules taking precedence on conflicts.

3. Fallback to CLAUDE.md

If no AGENTS.md is found in the project root, OpenCode falls back to CLAUDE.md. This fallback is explicitly designed for Claude Code migrants: your existing CLAUDE.md works in OpenCode without renaming. Once you have both files, AGENTS.md takes precedence.

opencode.json: Extending Discovery with the instructions Field

The opencode.json configuration file at the project root controls which instruction files get loaded. The instructions field accepts an array of paths and glob patterns:

{
  "instructions": [
    "AGENTS.md",
    "packages/*/AGENTS.md",
    "docs/agent-rules.md"
  ]
}

Each entry can be:

• A direct file path ("AGENTS.md", "docs/rules.md")
• A glob pattern ("packages/*/AGENTS.md" loads an AGENTS.md from every direct subdirectory of packages/)
• A remote URL ("https://your-org.example.com/shared-rules.md" — fetched at session start)

When the instructions field is present, OpenCode loads all matched files and concatenates them in order. The project root AGENTS.md and global ~/.config/opencode/AGENTS.md are still loaded; opencode.json adds to the stack rather than replacing it.

For a monorepo with per-package rules, this is the correct pattern:

{
  "instructions": [
    "AGENTS.md",
    "packages/api/AGENTS.md",
    "packages/web/AGENTS.md",
    "packages/shared/AGENTS.md"
  ]
}

Glob form is terser:

{
  "instructions": [
    "AGENTS.md",
    "packages/*/AGENTS.md"
  ]
}

Using /init to Auto-Generate AGENTS.md

OpenCode’s /init command scans the current repository and generates a project-appropriate AGENTS.md. It inspects:

• Package manager files (package.json, pyproject.toml, Cargo.toml, go.mod)
• Existing test runner configuration (jest.config.*, pytest.ini, .mocharc.*)
• Linter and formatter configs (.eslintrc, biome.json, .prettierrc)
• CI files (.github/workflows/, .gitlab-ci.yml)
• Existing CLAUDE.md or AGENTS.md (to migrate content)

The generated file includes a Commands section with the detected build, test, lint, and type-check commands — the section that has the highest impact on agent behavior.

After running /init, you get a working baseline. Customization is straightforward: open the generated file and add project-specific sections (architecture notes, files to avoid, naming conventions). The auto-generated content gives you the scaffolding; the manual additions give it specificity.

Commit the generated AGENTS.md immediately. It belongs in version control — other team members and CI environments benefit from it, and it prevents the file from drifting out of sync with the project’s actual toolchain.

OpenCode-Specific AGENTS.md Sections That Work Best

Not all AGENTS.md sections land equally in OpenCode. Based on observed behavior across the supported backends:

Commands (highest reliability)

The Commands section is processed reliably across all backends OpenCode supports. Exact terminal commands have low ambiguity — the model runs what you specify:

## Commands

Build: `npm run build`
Test: `npm test`
Test (single file): `npm test -- path/to/file.test.ts`
Lint: `npm run lint`
Type check: `npx tsc --noEmit`
Format: `npm run format`

Always include a single-file test command. Agents that run the full test suite after every change are slow; specifying the single-file invocation gets agents to run targeted tests.

Code Style Rules

Concrete style rules work well; vague preferences do not:

## Code Style

- TypeScript strict mode. No `any`.
- Named exports only. No default exports.
- Async functions: use async/await. No `.then()` chains.
- Error messages: lowercase, no trailing period.
- Variable names: descriptive nouns. No single letters except loop counters.

Rules like “write clean code” or “follow best practices” produce no measurable behavior change. Rules like “no default exports” are enforced.

What OpenCode Applies Inconsistently

When switching backends (Claude → GPT-4 → Gemini), tone and verbosity instructions are applied less consistently than structural rules. The Commands and Code Style sections are nearly backend-agnostic. Section-level behavioral instructions (“respond concisely”, “ask before deleting files”) vary more by model. If a behavioral rule is critical, test it with the specific backend in use.

Full AGENTS.md Template for a Node.js/TypeScript Project

# AGENTS.md

## Commands

Build: `npm run build`
Test: `npm test`
Test (single file): `npx jest path/to/file.test.ts`
Lint: `npm run lint`
Type check: `npx tsc --noEmit`
Format: `npx prettier --write .`

## Code Style

- TypeScript with strict mode enabled.
- No `any` types. Use `unknown` and narrow.
- Named exports only.
- Interfaces over type aliases for object shapes.
- Use `const` by default; `let` only when reassignment is necessary.

## Architecture

- `src/` — application source
- `src/api/` — HTTP handlers (no business logic)
- `src/services/` — business logic layer
- `src/db/` — database access (no raw SQL outside this directory)
- `tests/` — mirrors src/ structure

## Rules

- Run `npm test` and `npm run lint` before declaring work complete.
- Do not modify `src/db/migrations/`. Migrations are append-only.
- Do not commit `.env` files. Use `.env.example` as the template.
- PR titles follow Conventional Commits: `feat:`, `fix:`, `chore:`, etc.

opencode.json: Advanced Configuration

The full set of configuration options in opencode.json relevant to AGENTS.md:

{
  "instructions": [
    "AGENTS.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/your-org/shared-rules/main/AGENTS.md"
  ],
  "model": "claude-opus-4",
  "temperature": 0
}

Glob patterns use standard glob syntax. packages/*/AGENTS.md matches direct subdirectories only; packages/**/AGENTS.md matches all nested levels.

Remote URLs are fetched at session start. This is useful for organization-wide rules maintained centrally — one URL, all developers get updates automatically. The fetched content is treated identically to local AGENTS.md content.

Combining multiple instruction files concatenates content in array order. The last file in the array wins on any direct conflicts, so put the most specific (package-level) rules last.

Build Mode vs Plan Mode with AGENTS.md

OpenCode operates in two primary modes:

Build mode (default) is autonomous execution. The agent reads AGENTS.md, then writes files, runs terminal commands, and iterates without per-step confirmation. In this mode, the Commands section is the most impactful part of your AGENTS.md — the agent will run npm test (or whatever you specify) autonomously to verify its work.

Plan mode is read-only preview. The agent reads AGENTS.md and generates a step-by-step plan for what it would do, but does not write files or execute commands. It uses your AGENTS.md to inform the plan — architecture notes tell it which directories to target, code style rules shape the proposed changes — but nothing is executed.

When to rely on which AGENTS.md sections:

For teams new to OpenCode, run Plan mode first for complex tasks to verify the agent’s interpretation of your AGENTS.md before switching to Build mode.

OpenCode vs Claude Code: AGENTS.md Support Comparison

The key practical difference: Claude Code’s hierarchical discovery walks the directory tree automatically. OpenCode’s project-root discovery is simpler but requires explicit glob configuration for monorepos. For a flat single-package repository, the experience is nearly identical. For monorepos with per-package rules, OpenCode’s opencode.json glob patterns are more explicit but require a one-time setup.

FAQ

Does OpenCode read AGENTS.md?

Yes. OpenCode reads AGENTS.md from the project root automatically when you start a session. No additional configuration is required. For global personal rules, place a second AGENTS.md at ~/.config/opencode/AGENTS.md.

Where should I put AGENTS.md for OpenCode?

Place the project-level file in the Git repository root — the same directory as your package.json, Cargo.toml, or equivalent. For personal cross-project rules (preferred code style, commit format), use ~/.config/opencode/AGENTS.md. For monorepos, add per-package AGENTS.md files and reference them via glob patterns in opencode.json.

What is the difference between AGENTS.md and opencode.json instructions?

AGENTS.md is the instruction content — rules the agent follows. opencode.json is the configuration layer that controls which instruction files get loaded and in what order. Most projects need only an AGENTS.md. The opencode.json instructions field becomes useful when you have multiple instruction sources: per-package AGENTS.md files in a monorepo, or a centrally maintained remote URL.

How do I migrate from Claude Code to OpenCode using AGENTS.md?

If you have a CLAUDE.md and no AGENTS.md, OpenCode will use CLAUDE.md immediately — no action required. To align going forward, copy your CLAUDE.md to AGENTS.md and commit both. Remove Claude Code-specific syntax (the @import system, MCP tool references) from the AGENTS.md copy so it stays clean for multi-tool use. Keep your CLAUDE.md for Claude Code-specific features.

Does OpenCode read CLAUDE.md?

Yes, as a fallback. If OpenCode finds no AGENTS.md in the project root, it reads CLAUDE.md instead. When both files exist, AGENTS.md takes precedence. This fallback is explicitly designed so Claude Code teams can adopt OpenCode without renaming or duplicating their existing configuration.

Related Articles

• AGENTS.md Best Practices 2026: What 60,000+ Repos Teach Us
• AGENTS.md for Gemini CLI: How Google’s Agent Reads Your Instructions
• Writing Effective AGENTS.md: The Complete Guide
• AGENTS.md for OpenAI Codex: Complete Setup Guide

Secure OpenCode’s LLM API Keys

OpenCode supports multiple backends — Claude, GPT-4, Gemini, local models. Managing API keys for each without leaking them to your AGENTS.md or opencode.json? 1Password CLI’s op run injects each provider’s key at runtime with full audit logging.