Skip to content
maestria

Installation & Setup

@maestria/opencode adds the maestria main agent, one reviewer specialist, shared workflow rules, workflow modes, and methodology skills to OpenCode. Install it with the maestria CLI or with OpenCode’s own plugin commands.

Compatibility

Section titled “Compatibility”
OpenCode @maestria/opencode
V2 (2.0.28 or later) 0.9.0 and later
V1 0.8.0 and earlier

Prerequisites

Section titled “Prerequisites”
Section titled “Installation via CLI (Recommended)”
Terminal window
# Install the OpenCode plugin
npx maestria install opencode
Terminal window
# Verify installation
npx maestria status

The CLI runs opencode plugin add @maestria/opencode, which adds the package to the global plugins list. See the CLI documentation for more commands and options.

Alternative: OpenCode plugin commands
Terminal window
opencode plugin add @maestria/opencode

For a single project, add it to plugins in that project’s opencode.json(c) or .opencode/opencode.json(c) instead:

{
  "plugins": ["@maestria/opencode"],
}

OpenCode installs missing packages in the background when its server starts and reloads watched config changes automatically (OpenCode plugins).

Moving from OpenCode V1

Section titled “Moving from OpenCode V1”

OpenCode V2 reads the same config files as V1 but ignores the V1 plugin array, so an existing "plugin": ["@maestria/opencode@latest"] entry does nothing in V2. Run maestria update opencode (or maestria install opencode): it removes the maestria entry from the V1 plugin array and adds the package to plugins. Other plugins are kept, and so are comments outside the V1 plugin array.

Verify Installation

Section titled “Verify Installation”

Start a new OpenCode session. The maestria and reviewer agents are available, the /fein, /sonar, and /blitz commands are listed, and the global workflow rules are active. Read When to use maestria before choosing maestria.

Updating

Section titled “Updating”
Terminal window
npx maestria update opencode

Without the CLI, run opencode plugin update @maestria/opencode. OpenCode also checks unpinned plugins for updates when its server starts, without changing the installed package (OpenCode plugins).

Uninstalling

Section titled “Uninstalling”
Terminal window
npx maestria uninstall opencode

This runs opencode plugin remove for each global maestria entry and drops any maestria entry left in a V1 plugin array. Without the CLI, run opencode plugin remove @maestria/opencode with the exact configured specifier (for example @maestria/[email protected] when pinned). Remove project-level entries from that project’s config by hand.

Next Steps

Section titled “Next Steps”