Skip to content
maestria

Installation

Every host below installs the same @maestria/agent-plugins package. Pick your host, run its install steps, then start a fresh session. Hosts differ in what they can load; the overview table summarizes that, and usage covers day-to-day commands.

The maestria install <host> command hands the published npm package to the host’s own installer; Hermes instead installs from the repository’s default branch through its Git-based installer. It does not replace the host’s controls for permissions, trust, and session lifecycle.

Stage or check out the package

Section titled “Stage or check out the package”

Hosts without a maestria install command (Devin, ZCode) and any other Agent Plugins v1 client start from a staged directory:

Terminal window
npx maestria@latest plugin install

Install @maestria/agent-plugins through the selected client using its package installer or the staged directory. The exact activation command depends on the client.

The command prints a staged directory for your client’s installer or local-plugin setting. Staging does not activate the plugin or change client configuration. To validate an existing directory:

Terminal window
npx maestria@latest plugin validate /path/to/plugin

A successful check reports a valid manifest and the six skills. Use --json for a machine-readable report.

The command is intentionally namespaced as maestria plugin ...: maestria install manages runtime integrations and host installation flows; maestria plugin validates and stages artifacts.

To use a checkout instead, point the host at the directory containing plugin.json:

/path/to/maestria/packages/agent-plugins/

The checkout and the extracted npm archive share the same installation root. Follow the host’s enable and trust flow, then reload plugins or start a new session. Install this package once per host namespace and remove the superseded standalone integration to avoid duplicate resources.

If utilities do not appear, confirm the selected directory contains plugin.json and skills/, check host trust settings, and reload discovery.

Claude Code

Section titled “Claude Code”

@maestria/agent-plugins is a declarative Claude Code plugin. Its .claude-plugin/plugin.json manifest lists the four shared agents/<role>.md profiles and the three shared commands/*.md workflows explicitly, because Claude rejects directory agent selectors, and Claude Code adds the six skills from skills/ by convention. No build step or runtime code is required. The host-side model is described in the Claude Code plugin components guide.

Prerequisites. Claude Code with the claude CLI on PATH, and Node.js with npm for maestria install claude-code. Node.js and pnpm are needed only to regenerate files from the canonical directives.

Install and manage.

Terminal window
npx maestria@latest install claude-code

The CLI downloads @maestria/agent-plugins from npm, stages it in a local marketplace under ~/.cache/maestria/, and delegates installation to Claude Code. Plugin state and scope stay in the host runtime. Check, update, or remove the installation with:

Terminal window
npx maestria@latest status
Terminal window
npx maestria@latest update claude-code
Terminal window
npx maestria@latest uninstall claude-code

Claude Code’s marketplace update path selects the latest package. Exact version pinning is not available through maestria update claude-code --version.

Direct marketplace install.

Terminal window
claude plugin marketplace add agustinusnathaniel/maestria
claude plugin install maestria@maestria --scope user

The repository marketplace points at ./packages/agent-plugins, so a direct install uses the repository’s default branch; maestria install claude-code installs the published npm release instead. In Claude Code 2.1.275 or later, one in-session command adds the marketplace and installs the plugin:

/plugin install maestria --marketplace agustinusnathaniel/maestria

Try it without installing. From a checkout, load the plugin for one session (--plugin-dir can be passed several times), or validate it:

Terminal window
claude --plugin-dir ./packages/agent-plugins
claude plugin validate ./packages/agent-plugins --strict

--strict treats warnings as errors and is the recommended CI check. A clean run prints ✔ Validation passed. Stop passing --plugin-dir to unload the plugin. The staging directory is safe to remove afterwards: rm -rf ~/.cache/maestria/claude-code-marketplace.

Verify.

  1. Start a session with the plugin loaded.
  2. Check the /plugin manager and the /context Custom Agents tab. Components are namespaced under maestria.
  3. Confirm the read-only roles (maestria:adventurer, maestria:architect, maestria:reviewer) cannot call Write or Edit.
Component Identifier
Native agents maestria:<role> through the Agent tool
Native commands /maestria:fein, /maestria:sonar, /maestria:blitz
Skills maestria:handoff, maestria:iteration-limits, maestria:create-pull-request, maestria:docs-update, maestria:diagnose, maestria:plan

Limits. disallowedTools: Write, Edit filters those tools for the three read-only roles. Shell-mediated writes are outside the filter, and role text remains guidance. Profiles set no model, so Claude uses the main conversation’s model. Claude Code ignores permissionMode, hooks, and mcpServers agent frontmatter for plugin-loaded agents; maestria ships no hooks or MCP server and does not modify CLAUDE.md. Strict validation passes on Claude Code 2.1.295, and an offline fixture (2026-10-12) loaded the reviewer from the shared profile with Write and Edit unavailable and the full role and global policy in the child context. Model judgment, shell isolation, other specialists, other CLI versions, account sync, Cowork, and Desktop behavior are not covered. See the host verification record and compatibility.

Claude Code Desktop

Section titled “Claude Code Desktop”

Claude Code Desktop shares configuration with the CLI for local sessions. For an existing CLI installation, open a local or SSH Code session in Desktop; the plugin manager can show, enable, disable, or uninstall plugins from configured marketplaces.

To install from the Desktop UI, first add the maestria marketplace in the CLI (claude plugin marketplace add agustinusnathaniel/maestria). Then, in a local or SSH Code session, click + beside the prompt, choose Plugins, select Add plugin, and install maestria from the configured marketplace. Verify it in the same menu or with /plugin in the CLI. The Desktop plugin browser is unavailable in cloud sessions, and plugins installed from Desktop are not available there. See the Claude Code Desktop guide.

Claude Chat and Cowork

Section titled “Claude Chat and Cowork”

The native commands work in Claude Code, Desktop Code, and Cowork. Claude account plugins can expose commands and skills in Chat, which ignores native agents. Cowork supports plugin agents and hooks. Account plugins sync into Claude Code when you are signed in with the same account on Claude Code 2.1.273 or later. maestria’s account sync and Cowork behavior are unverified. See Claude’s plugin surface guide.

Codex

Section titled “Codex”

Codex plugins cannot ship agents, so a full setup has two parts. The Codex plugin supplies the six skills (handoff, iteration-limits, create-pull-request, docs-update, diagnose, and plan). A companion install adds the four native agents and the routing instructions. Which parts you get depends on how you install:

Install path You get
maestria install codex (Codex CLI) Plugin utilities, four agent TOMLs, and a managed routing block in global instructions
codex plugin add or a marketplace (CLI or desktop) The six plugin skills only

Codex CLI

Section titled “Codex CLI”

The maestria CLI installs the skills through Codex’s plugin manager, copies the maestria-<role>.toml roles to $CODEX_HOME/agents/, and adds a marked orchestration block to $CODEX_HOME/AGENTS.md or $CODEX_HOME/AGENTS.override.md. It preserves unrelated instructions and does not write config.toml, register models, add MCP servers, or install hooks.

Prerequisites. Codex CLI with plugin and native custom-agent support (the inspected AgentPlugin loader is version 0.153.4; other versions need rechecking), plus Node.js 22.12.0 or later and npm on PATH.

Install.

Terminal window
npx maestria@latest install codex

The CLI stages a local marketplace at ~/.cache/maestria/codex-marketplace, then delegates to Codex (codex plugin marketplace add, codex plugin add maestria@maestria). It also copies the agent TOMLs and updates the managed instructions. The plugin cache and enabled state belong to Codex.

Verify.

  1. Check the host status:

    Terminal window
    npx maestria@latest check codex

  2. List the installed plugin with codex plugin list --json and look for maestria@maestria with installed: true.

  3. Start a fresh Codex session, since plugin discovery is session-sensitive, and confirm the six skills ($maestria:handoff, $maestria:iteration-limits, $maestria:create-pull-request, $maestria:docs-update, $maestria:diagnose, $maestria:plan) are available.

  4. Confirm ~/.codex/agents/maestria-*.toml exists (or the equivalent $CODEX_HOME/agents/ directory). Ask Codex to delegate with agent_type: "maestria-builder" and use maestria-reviewer for independent review.

  5. Ask for a meaningful task without a skill prefix and confirm the primary session follows the routing guidance. Try SONAR: trace authentication without editing.

Update and remove.

Terminal window
npx maestria@latest update codex
Terminal window
npx maestria@latest uninstall codex

Codex CLI does not expose a separate plugin update command. The maestria CLI refreshes the staged npm package, removes and re-adds maestria@maestria, then refreshes the agent TOMLs while preserving your model settings. Exact version pinning is not supported through maestria update codex --version. Uninstall removes only the maestria-managed agent files and marked block; existing Codex instructions and unrelated agent files stay untouched. maestria update removes retired Codex TOMLs automatically (manifest-tracked).

Direct plugin install. The repository also exposes a native Codex marketplace entry backed by the published npm package:

Terminal window
codex plugin marketplace add agustinusnathaniel/maestria
codex plugin add maestria@maestria

codex plugin add expects a PLUGIN@MARKETPLACE selector, not a bare npm package name. Direct installation adds only the plugin and its six skills: it does not copy the agent TOMLs or modify global AGENTS.md. Codex 0.153.4 discovers the conventional root skills/ directory, and its AgentPlugin loader ignores the overlay skills selector, so that selector cannot turn commands or agents into skills. The .codex-plugin/plugin.json compatibility manifest supplies presentation metadata.

Evidence. Package and installer tests cover the companion payloads. The 2026-08-26 marketplace smoke used Codex CLI 0.145.0 and the former standalone package; no fresh CLI end-to-end run covers the consolidated archive. See compatibility.

Codex desktop

Section titled “Codex desktop”

This setup installs only the six skills in Codex in the ChatGPT desktop app. It does not install the agent TOMLs or the managed routing instructions; use the Codex CLI path for those.

Create ~/.agents/plugins/marketplace.json with this entry:

{
  "name": "maestria-local",
  "interface": { "displayName": "Maestria" },
  "plugins": [
    {
      "name": "maestria",
      "source": {
        "source": "npm",
        "package": "@maestria/agent-plugins",
        "version": "latest"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

The marketplace file is user-scoped, and the npm source requires the npm CLI. See the OpenAI plugin packaging guide for marketplace fields and source behavior.

  1. Restart the ChatGPT desktop app so Codex reads the marketplace file.
  2. Open the Plugins Directory, choose the Maestria marketplace, and install maestria.
  3. Start a new Codex chat and confirm the four $maestria:<skill> skills appear.

This flow follows the host’s documented local-marketplace setup. maestria has not been runtime-tested in the desktop app, and Codex still owns permissions, approvals, and sandbox behavior.

Cursor

Section titled “Cursor”

@maestria/agent-plugins is a declarative Cursor plugin for Cursor IDE and Cursor CLI, with no build step. The same plugin drives both surfaces.

Prerequisites. Cursor IDE and/or Cursor CLI (agent on PATH). Node.js and npm are needed only for the maestria CLI.

Install.

Terminal window
npx maestria@latest install cursor
Terminal window
npx maestria@latest status

The plugin installs to ~/.cursor/plugins/local/maestria. Restart Cursor IDE afterwards so Customize → Plugins picks it up. For Cursor CLI, pass the plugin directory or use the local plugins directory:

Terminal window
agent --plugin-dir ~/.cursor/plugins/local/maestria

Update and remove.

Terminal window
npx maestria@latest update cursor
Terminal window
npx maestria@latest uninstall cursor

What gets installed.

Path Purpose
.cursor-plugin/plugin.json Plugin manifest
agents/*.md Four complete specialist Task agents (shared across hosts)
skills/*/SKILL.md handoff and iteration-limits utilities and the bundled create-pull-request, docs-update, diagnose, and plan skills
rules/cursor/maestria-global.mdc Always-apply global policy and routing (alwaysApply: true)
commands/*.md Complete workflow slash commands (shared)

Profiles embed complete role and global policy, so no role skill preload is needed. Other hosts’ frontmatter keys do not affect Cursor loading.

Models. maestria configure cursor at global level edits ~/.cursor/plugins/local/maestria/agents/<role>.md. maestria update cursor carries configured models over, reading the shared profile first and falling back to a legacy agents/cursor/ copy from earlier installs.

Kimi Code

Section titled “Kimi Code”

The Kimi manifest points at the four shared profiles in agents/, the three shared commands in commands/, and, through systemPromptPath, the root AGENTS.md it shares with Devin, Codex, and Hermes. Root skills/ carries the six skills.

Prerequisites. A Kimi Code version that supports native plugin agents, commands, and systemPromptPath (see the official plugin guide), and Node.js 22.12 or later with npm for the maestria CLI.

Install and reload.

Terminal window
npx maestria@latest install kimi-code

Inside Kimi Code, reload plugins or start a new session, then confirm maestria is enabled and exposes its specialists and commands:

/reload
/plugins list
/plugins info maestria

For manual installation, extract npm pack @maestria/agent-plugins@latest, run /plugins install <extracted-directory>, then /reload.

Update and remove.

Terminal window
npx maestria@latest update kimi-code
Terminal window
npx maestria@latest uninstall kimi-code

Updates replace the managed package, so back up local changes first. Your own permission rules or hooks stay separate from this plugin.

What loads.

Component Purpose
Four native specialists Complete role and global policy for adventurer, architect, builder, and reviewer
Three native commands Complete fein, sonar, and blitz workflows with task arguments ($ARGUMENTS is substituted)
systemPromptPath to AGENTS.md Complete policy, routing, and mode guidance within Kimi’s 32 KB contribution limit
Six skills handoff, iteration-limits, create-pull-request, docs-update, diagnose, plan

The integration uses neither sessionStart.skill nor skillInstructions. Native specialists replace the former mapping to the built-in coder, explore, and plan agents. Child methodology does not depend on a parent loading role skills.

Limits. The three read-only roles use disallowedTools to deny Write and Edit, the tool names registered by Kimi v0.38.0 and v2.1.1 source. Earlier releases of this package listed WriteFile and StrReplaceFile, which matched nothing, so read-only was not effective before. This filter is not a shell sandbox. Kimi ignores other hosts’ readonly and model keys, and the plugin-agent format has no per-agent model field, so the host selects the model. The package adds no hooks or MCP server. Nothing here has been live-run: Kimi CLI 2.1.1 needs a Kimi Code subscription. See compatibility.

Troubleshooting.

Symptom Check
Plugin missing Run /plugins list and /plugins info maestria; verify the installation directory
Old skills or agents appear Remove the former standalone plugin, then /reload or start a new session
Session context does not load Confirm the host supports systemPromptPath and the package’s root AGENTS.md exists
Native role missing Confirm the host supports plugin agents and the manifest points at ./agents/
Reviewer can edit through a shell Native write-tool denial does not restrict shell execution

Devin

Section titled “Devin”

Devin reads @maestria/agent-plugins through .devin-plugin/plugin.json. The package supplies conventional root agent profiles and always-on policy and routing in root AGENTS.md. The manifest declares only skills, which adds the six skills. Devin has no plugin commands component, so there are no slash commands; use mode keywords instead.

Install. Stage a validated package, then install the printed directory through Devin:

Terminal window
npx maestria@latest plugin install
Terminal window
devin plugins install --local /path/to/staged-plugin
devin plugins info maestria

--local links the directory on this machine. For personal plugin sync to cloud sessions and other devices, install from the repository subdirectory:

Terminal window
devin plugins install agustinusnathaniel/maestria#packages/agent-plugins

Changes apply to new sessions. Use Reindex plugins on Devin’s Customize page to refresh the web listing. See the official installation formats and Customize guide.

Limits. Native plugin agents load in local CLI and Desktop sessions, not cloud sessions. Personal plugins can supply the selected skills and policy to cloud sessions, but that does not add plugin subagents there. Devin offers an allowed-tools allowlist but no denylist or read-only field, so read-only roles are prompt-level only. No hooks, MCP server, or automation ship here. Devin CLI 3000.11.3 (devin plugins info, 2026-10-12, skills rechecked 2026-10-13) listed the previous layout’s seven profiles and four skills, and AGENTS.md as always on; it ignores the .toml profiles and the per-host rule folders, and lists rules/global.md as manual. The package now ships four profiles and six skills, which have not been re-probed on Devin. Agent task execution was not run. See compatibility.

ZCode

Section titled “ZCode”

The ZCode manifest (.zcode-plugin/plugin.json) selects the shared commands/ and skills/ directories, and ZCode discovers agents/ by convention: four specialist profiles, three native commands, and six skills. They are the same files other Markdown hosts use. ZCode ignores file lists and loads only .md agents, so the manifest uses directory selectors.

Install. Stage the plugin in a directory beside a ZCode marketplace file:

Terminal window
mkdir -p ./maestria-zcode
Terminal window
npx maestria@latest plugin install --destination ./maestria-zcode/plugin

Create ./maestria-zcode/marketplace.json with this entry:

{
  "name": "maestria-local",
  "plugins": [
    {
      "name": "maestria",
      "source": "./plugin"
    }
  ]
}

In ZCode, open a workspace, then choose Settings → Plugins → Create → Add marketplace and select the ./maestria-zcode directory. Find maestria in the Personal section and click Install. Staging alone does not install or activate the plugin. See ZCode’s plugin guide for current UI labels and the marketplace format.

Limits. The package adds no MCP server, hooks, or executable extension. ZCode has no plugin rules component, so profiles and commands carry their own policy. The three read-only roles declare disallowedTools: [Write, Edit], which ZCode enforces by removing those tools from the subagent’s tool list (from the ZCode source; not live-run). Shell access remains, so this is a tool filter, not a sandbox. ZCode drops unknown keys such as readonly and subagents. Profiles set no model, so ZCode uses the main conversation’s model. A locally installed plugin does not follow a remote workspace by default; use ZCode’s Sync Plugin control for that workspace. See compatibility.

OMP

Section titled “OMP”

Oh My Pi (OMP) uses conventional discovery on the package: four task profiles (agents/<role>.md), three commands, one always-apply rule (rules/global.md), and six skills. An empty package.json#omp entry registers the data-only package. OMP owns plugin activation, task execution, permissions, and session behavior.

Install.

  1. Install the package with the maestria CLI, which runs omp plugin install @maestria/agent-plugins:

    Terminal window
    npx maestria@latest install omp

  2. Confirm OMP registered the package with omp plugin list.

  3. Start a new session and confirm /fein, /sonar, and /blitz are available, along with the four specialist task identities. Rule discovery supplies policy and routing.

You can also install directly through OMP’s package manager, which doubles as the update command:

Terminal window
omp plugin install @maestria/agent-plugins@latest

Update and remove.

Terminal window
npx maestria@latest update omp
Terminal window
npx maestria@latest uninstall omp

Or remove the package with omp plugin uninstall @maestria/agent-plugins. If the retired @maestria/omp executable package is still installed, remove it separately. Its hooks, interception, review-mode enforcement, goal mirroring, and per-agent model configuration were not carried into this data-only integration.

Resources.

Resource Purpose
agents/<role>.md Four specialist profiles with complete role and policy
/fein, /sonar, /blitz Complete native mode commands with routing and policy
rules/global.md Always-apply global policy and routing for the main session
skills/ handoff, iteration-limits, create-pull-request, docs-update, diagnose, plan

Profiles, commands, and rules are generated from canonical sources and shared with other Markdown hosts, so no role or global-rules skill preload is needed. By default, profiles inherit the parent model.

Limits. The data-only integration declares no executable extension, task wrapper, lifecycle hook, review interceptor, goal wrapper, automation, or MCP server; the retired runtime’s enforcement does not carry over. OMP has no denylist, so the shared readonly and disallowedTools keys are not enforced and read-only is prompt-level. A real OMP 18.4.8 loader probe (scripts/e2e/omp-plugin-discovery.ts, 2026-10-13) on the packed archive and a git root found 7 agents, 3 commands, 1 rule, and 4 skills for the previous layout (the package now ships 4 profiles and 6 skills), and did not load .toml files. A real isolated install lifecycle run (2026-10-13) passed 39 of 39 checks with the previous four skills; an earlier probe (2026-10-11) covered the previous eight-profile layout. No inference or task spawning ran, so model judgment and runtime permission enforcement are unverified. See the host verification record. For the separate Pi runtime extension, use the Pi reference.

Hermes

Section titled “Hermes”

Hermes consumes the root portable manifest and the six skills in @maestria/agent-plugins. It needs a Hermes version that supports portable Agent Plugins. Portable installation supplies only the six skills; full routing needs the optional manual context below.

Install.

Terminal window
npx maestria@latest install hermes

Or install through Hermes:

Terminal window
hermes plugins install \
  agustinusnathaniel/maestria/packages/agent-plugins --enable
hermes plugins list

For unreleased work, copy the plugin into an isolated Hermes home and use the host enable command. The plugin should appear as maestria. Enable it if your installer leaves it disabled, then start a new session.

Verify skills. Ask Hermes to call skills_list to discover the plugin’s fully qualified skill names, then skill_view to load one of the six skills, such as handoff. Hermes derives an agent-plugin-<slug>-<hash> namespace for portable plugins, so do not assume maestria:<skill>.

Update and remove.

Terminal window
hermes plugins update maestria
hermes plugins remove maestria

The equivalent maestria commands are update hermes and uninstall hermes. Git-based installation does not support npm version pinning.

Migrate the Python adapter. The maestria installer disables maestria-hermes after the replacement installs successfully; a failed install leaves the old adapter enabled. For direct installation, disable it yourself after verifying the new plugin:

Terminal window
hermes plugins disable maestria-hermes

The Python adapter’s mode commands, role gates, lifecycle hooks, and OpenCode bridge are retired, and legacy files and user data are not deleted by migration. maestria adds no Python adapter, memory provider, background schedule, OpenCode bridge, or permission gate. Hermes owns permissions, trust, delegation, and session behavior. See compatibility for dated discovery evidence and its limits.

Hermes manual context

Section titled “Hermes manual context”

For full policy, routing, and mode guidance, manually add the contents of the bundled root AGENTS.md to the context file Hermes already selects, preserving existing instructions. If no context file exists, create one appropriate for your project. The package and CLI do not modify these user files or import the bundled context automatically.

Hermes loads only the first applicable project context type. It searches for .hermes.md or HERMES.md from the current directory toward the Git root, then falls back to AGENTS.md in the current directory, followed by other supported context types. Do not create a higher-priority .hermes.md that hides an existing AGENTS.md. See the official prompt-assembly order.

Start a new session or rebuild the host prompt, then verify that the selected context includes the complete policy, router, and mode instructions. Host context-size settings can truncate the bundled guidance, which the generator keeps under 32 KB. Hermes subagents skip project context files, so manual delegation must explicitly pass the relevant role guidance, global policy, and task constraints to each child.

Manual context remains advisory. It does not register native specialist profiles, create mode commands, or add hooks or enforcement.