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)”

The maestria CLI provides a unified interface for installing and managing maestria plugins across all supported platforms:

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 the plugin with a single command:

Global install (available in all projects):

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

Project-level install (current project only):

Terminal window
opencode plugin @maestria/opencode@latest

Or, add it manually to your OpenCode config:

  1. Open your OpenCode config

    • Global: ~/.config/opencode/opencode.jsonc
    • Project-level: .opencode/opencode.jsonc

  2. Add the plugin to the plugin array

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

  3. Restart OpenCode

    The plugin auto-installs from npm on session start. Agents and rules are available immediately.

Verify Installation

Section titled “Verify Installation”

Start a new OpenCode session. The 8 agents are ready for delegation via @ mention. Read When to use Maestria before choosing @orchestrator: direct execution or one specialist is often better for small tasks and expensive models.

The global workflow rules are active in every prompt. You will see them reflected in how agents respond, delegate, and structure their output.

Updating

Section titled “Updating”

To update via the maestria CLI:

Terminal window
npx maestria update opencode
Alternative: Platform-native update

OpenCode does not auto-update plugins. Packages are cached locally in ~/.cache/opencode/packages/<name>@<version>/ - the npm registry is not consulted if the package is already cached. To update, 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 (bypassing the local cache), clear the cache first:

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

Then re-run the install command (with or without -g as appropriate).

Run opencode debug paths to see the cache directory resolved for your platform.

Configuring Workflow Modes

Section titled “Configuring Workflow Modes”

The orchestrator responds to three mode keywords that adjust the pipeline depth:

Keyword Full form Pipeline Use case
fein Full pipeline thinker → worker → verifier (adaptive order) Production-grade, mandatory review
sonar Research adventurer → architect/planner → STOP Understanding before committing
blitz Fast implementation direct when the host permits; otherwise permitted specialist Quick fixes, known territory

The keyword is detected at any position in your message, case-insensitively. Most restrictive keyword wins (fein > sonar > blitz). Code blocks are excluded from detection.

To disable a mode, set modes.disabledKeywords in your plugin configuration:

{
  "plugin": ["@maestria/opencode", { "modes": { "disabledKeywords": ["blitz"] } }],
}

Direct delegation. Any agent can be invoked directly by typing @agentname in your prompt. For example, @reviewer review my latest changes or @adventurer find where authentication is handled.

Manager delegation. For complex, unfamiliar, or high-risk tasks involving multiple steps, let @orchestrator handle the pipeline. It decomposes the work and dispatches each piece to the right specialist automatically.

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:

  1. Open your OpenCode config file

    • Global: ~/.config/opencode/opencode.jsonc
    • Project-level: .opencode/opencode.jsonc

  2. Remove the plugin from the plugin array

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

  3. Restart OpenCode

    The @maestria/opencode agents and rules will no longer be available. Other OpenCode plugins you have installed remain unaffected.

You can also optionally delete the cached package:

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

Next Steps

Section titled “Next Steps”