Configure AGENTS.md for persistent project rules, add local and remote MCP servers in opencode.json, customize keybinds and themes, and extend OpenCode with plugins.
AGENTS.md is OpenCode's rules file. It provides persistent project context to every OpenCode session without having to paste the same background in every conversation.
The fastest way to create a useful AGENTS.md is to run /init:
# SST v3 Monorepo
This is an SST v3 monorepo with TypeScript. Bun workspaces for package management.
## Build, Lint, and Test
- Build: `bun run build`
- Lint: `bun run lint`
- Test: `bun run test`
- Type check: `bun run typecheck`
- Always run tests after making changes to `packages/core/`
## Project Structure
- `packages/core/` — shared business logic, imported as `@my-app/core/*`
- `packages/functions/` — Lambda handlers
- `infra/` — SST infrastructure split by service (storage.ts, api.ts, web.ts)
## Code Standards
- TypeScript strict mode — no `any`, no `// @ts-ignore`
- All API errors return `{ code: string, message: string }` JSON
- Database queries go in `packages/core/`, not in Lambda handlers
## Development Setup
Run `yarn db:seed` before starting local dev — the database must have seed data.Focus on things that are not obvious from filenames: architectural decisions, command order, and gotchas for new contributors.
| File | Scope |
|---|---|
| ./AGENTS.md | Project (committed to Git, shared with team) |
| ~/.config/opencode/AGENTS.md | Global (personal rules across all projects) |
| ./CLAUDE.md | Fallback if no AGENTS.md exists (Claude Code compat) |
| ~/.claude/CLAUDE.md | Fallback global (if no OpenCode global AGENTS.md) |
OpenCode is compatible with Claude Code conventions. If no AGENTS.md exists in your project, it reads CLAUDE.md as a fallback.
Instead of duplicating rules into AGENTS.md, point OpenCode at your existing documentation in opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"CONTRIBUTING.md",
"docs/code-standards.md",
".cursor/rules/*.md",
"packages/*/AGENTS.md"
]
}Glob patterns are supported. Remote URLs also work:
{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
]
}All instruction files are combined with your AGENTS.md. Remote instructions time out after 5 seconds.
Create opencode.json in your project root (or ~/.config/opencode/opencode.json for global config):
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-6",
"instructions": ["CONTRIBUTING.md"],
"mcp": {},
"tools": {}
}The $schema key enables autocomplete and validation in VS Code and other JSON-aware editors.
MCP (Model Context Protocol) servers add external tools to OpenCode. Tools appear alongside built-in tools and are available to the LLM automatically.
MCP servers add to your context window. Each server's tools consume tokens even when not actively used. Be selective about which servers you enable.
Run an MCP server as a subprocess:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-local-mcp": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
"enabled": true,
"environment": {
"MY_ENV_VAR": "value"
}
}
}
}Connect to an MCP server over HTTP:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}"
}
}
}
}Use {env:VARIABLE_NAME} syntax to inject environment variables safely without hardcoding secrets.
Context7 — search up-to-date library documentation:
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp"
}
}
}Add to your AGENTS.md:
When you need to search documentation for a library, use `context7` tools.Sentry — query issues, projects, and error data with OAuth:
{
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}Authenticate after adding:
Grep by Vercel — search code examples across GitHub:
{
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
}
}
}Disable a specific server globally:
{
"tools": {
"my-mcp-foo": false
}
}Disable all tools from a server using a glob pattern:
{
"tools": {
"my-mcp*": false
}
}Enable a server only for a specific agent:
{
"mcp": {
"my-mcp": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true
}
},
"tools": {
"my-mcp*": false
},
"agent": {
"my-agent": {
"tools": {
"my-mcp*": true
}
}
}
}# List all MCP servers and auth status
opencode mcp list
# Manually trigger authentication for a server
opencode mcp auth <server-name>
# Remove stored credentials
opencode mcp logout <server-name>
# Debug a failing connection
opencode mcp debug <server-name>Configure providers and models beyond what /connect offers. Example — using a local Ollama model:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama3.2": {
"name": "Llama 3.2"
}
}
}
}
}The same pattern works for LM Studio (http://127.0.0.1:1234/v1), llama.cpp server (http://127.0.0.1:8080/v1), and any OpenAI-compatible endpoint.
For a custom base URL on a known provider (e.g., proxy):
{
"provider": {
"anthropic": {
"options": {
"baseURL": "https://my-proxy.example.com/v1"
}
}
}
}OpenCode ships with multiple themes. Customize via the config:
{
"$schema": "https://opencode.ai/config.json",
"theme": "catppuccin-mocha"
}Browse available themes at opencode.ai/docs/themes.
Remap keys in opencode.json under the "keybind" key. See all defaults at opencode.ai/docs/keybinds.
Plugins add provider integrations and workflow enhancements:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-gitlab-plugin"]
}Install the plugin via npm:
npm install -g opencode-gitlab-pluginSee the ecosystem at opencode.ai/docs/ecosystem.
AGENTS.md is your project's persistent AI rules file — run /init to generate it and commit it to Git. opencode.json is the config file for providers, MCP servers, tools, themes, and instructions. Local MCP servers run as subprocesses; remote servers connect over HTTP with optional OAuth. Manage authentication with the opencode mcp CLI commands. Plugins extend OpenCode for GitLab, Helicone sessions, and more.