Skip to content
maestria

Installation & Setup

@maestria/opencode adds an orchestrator, seven specialists, and shared workflow rules to OpenCode. Install it with the maestria CLI or add it to your OpenCode configuration.

Prerequisites

Section titled “Prerequisites”
  • OpenCode CLI (latest version)
  • Node.js 22.12+ - Required for plugin resolution. Earlier versions are not supported.
Section titled “Installation via CLI (Recommended)”
Terminal window
# Install the OpenCode plugin
npx maestria install opencode
Terminal window
# Verify installation
npx maestria status

See the CLI documentation for more commands and options.

Alternative: Manual setup

Install globally (all projects) or for the current project only:

Terminal window
opencode plugin @maestria/opencode@latest -g
opencode plugin @maestria/opencode@latest

Or add it manually to ~/.config/opencode/opencode.jsonc (global) or .opencode/opencode.jsonc (project-level):

{
  "plugin": ["@maestria/opencode@latest"],
}

Restart OpenCode. The plugin installs from npm at session start, and agents and rules are ready immediately.

Verify Installation

Section titled “Verify Installation”

Start a new OpenCode session. The 8 agents are ready for delegation via @ mention, and the global workflow rules are active in every prompt. Read When to use maestria before choosing @orchestrator.

Updating

Section titled “Updating”
Terminal window
npx maestria update opencode

OpenCode does not auto-update plugins. Packages are cached in ~/.cache/opencode/packages/<name>@<version>/, and the registry is not consulted when a package is already cached. Re-run the install command with the same scope as the original install:

Terminal window
# If installed globally
opencode plugin @maestria/opencode@latest -g --force


# If installed at project level
opencode plugin @maestria/opencode@latest --force

Use --force to replace an existing config entry. To force a fresh install from npm, clear the cache first:

Terminal window
rm -rf ~/.cache/opencode/packages/@maestria/opencode*

On Windows, use Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\@maestria\opencode*" (PowerShell) or rmdir /s /q "%USERPROFILE%\.cache\opencode\packages\@maestria" (CMD).

Uninstalling

Section titled “Uninstalling”

OpenCode has no built-in command to remove a plugin. The maestria CLI can print the removal steps for your platform: run maestria uninstall opencode (see CLI uninstall).

To uninstall manually, remove the entry from the plugin array in your OpenCode config file:

{
  "plugin": [
    // Remove or comment out the line below:
    // "@maestria/opencode@latest",
  ],
}

Restart OpenCode. The @maestria/opencode agents and rules will no longer be available; other OpenCode plugins remain unaffected. You can also delete the cached package with rm -rf ~/.cache/opencode/packages/@maestria/opencode*.

Next Steps

Section titled “Next Steps”