Skip to content
Maestria

Installation & Setup

@maestria/opencode is an npm plugin for OpenCode that turns your AI coding environment into a disciplined engineering workstation. It bundles 8 specialized agents and global workflow rules - all installed with a single line of configuration. No manual setup, no prompt engineering, no forgotten context between sessions.

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 for this platform
npx maestria install opencode


# 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. Try typing @orchestrator to kick off your first task - the manager agent decomposes it and hands pieces to the right specialist.

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 builder direct 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 tasks involving multiple steps, let @orchestrator handle the entire pipeline. It decomposes the work and dispatches each piece to the right specialist automatically.

Uninstalling

Section titled “Uninstalling”

There is no CLI command to remove a plugin. To uninstall, edit your OpenCode config file and remove the entry from the plugin array:

  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”