README

Research on whether OpenCode requires restart after updating configuration files like AGENTS.md, .opencode/agent/*.md, and .opencode/command/*.md.

Key Finding

Yes, OpenCode must be restarted for command and agent configuration changes to take effect.

According to the OpenCode Commands documentation:

IMPORTANT - Command Updates:

When slash command files (.claude/commands/*.md) are modified, Claude Code must be restarted for changes to take effect

After updating command definitions, ask the user to restart Claude Code before testing the commands

Command changes are not hot-reloaded; they require a full restart of the Claude Code session

This same principle applies to agent configuration changes in .opencode/agent/*.md files.

Configuration File Locations

OpenCode looks for configuration in two locations:

Global: ~/.config/opencode/ - User-level configuration
Per-project: .opencode/ - Project-specific configuration

Command Files

Location: .opencode/command/*.md or ~/.config/opencode/command/
Reload behavior: Requires restart

Agent Files

Location: .opencode/agent/*.md or ~/.config/opencode/agent/
Reload behavior: Requires restart (implied from command behavior)

Configuration JSON

Location: opencode.json or opencode.jsonc
Reload behavior: Not explicitly documented

Supported Configuration Methods

1. Markdown Files (Per-Command/Agent)

Commands: .opencode/command/test.md → /test command
Agents: .opencode/agent/review.md → review agent
Status: Requires restart after changes

2. JSON/JSONC Configuration

File: opencode.json or opencode.jsonc in project root
Allows centralized configuration of multiple commands and agents
Status: Reload behavior not explicitly documented

AGENTS.md vs Configuration Files

Important distinction:

AGENTS.md: Project documentation file generated by /init command. Contains project description, structure, and coding patterns. This is metadata about your project and is loaded/read dynamically by OpenCode.
.opencode/agent/*.md and .opencode/command/*.md: Actual configuration files that define agent and command behavior. These require restart.

The documentation doesn’t indicate that AGENTS.md itself needs a restart when updated.

Summary

File	Location	Changes Require Restart?
AGENTS.md	Project root	Unknown (likely dynamic)
Command markdown	`.opencode/command/*.md`	Yes
Agent markdown	`.opencode/agent/*.md`	Yes
Commands in JSON	`opencode.json`	Not documented
Agents in JSON	`opencode.json`	Not documented