Skip to content
maestria

Installation & Setup

@maestria/kimi-code is a declarative plugin with no build step.

Prerequisites

Section titled “Prerequisites”
  • Kimi Code v0.38.0 or later for the verified plugin registry, systemPromptPath, and AgentSwarm behavior.
  • Node.js 22.12 or later and npm when using the maestria CLI.

Install

Section titled “Install”

  1. Install:

    Terminal window
    # Install for Kimi Code
    npx maestria install kimi-code

  2. Check the native plugin record:

    Terminal window
    # Check installation
    npx maestria status

  3. Start a new session so the session-start skill and system prompt load:

    /reload
    /new

Manual Install

Section titled “Manual Install”

To control extraction yourself, run npm pack @maestria/kimi-code@latest, extract the tarball, then run /plugins install <extracted-directory> from a Kimi Code session. Delete the temporary files afterward.

Optional Session Controls

Section titled “Optional Session Controls”

[[hooks]] and [[permission.rules]] blocks in ~/.kimi-code/config.toml are the only tool-layer enforcement; persona text alone is advisory. The default installation adds neither. Hooks are executable code: review them before enabling. Permission rules apply session-wide, so a deny rule for review also blocks builder and writer work.

Note (2026-09-22): the recommended hooks below were previously recorded in ADR-KC-001 and are re-homed here, next to the install steps, so this guide is the single how-to reference.

The recommended session controls live in the user’s config.toml, not the plugin manifest; the user copies them in:

  • PreToolUse on Bash - block destructive commands (Kimi’s upstream hooks documentation gives an example that exits 2 to block)
  • UserPromptSubmit - append a session reminder to every user message; the closest approximation of system-prompt injection
  • PreCompact / PostCompact - observation-only logging of compaction cycles

PreToolUse, UserPromptSubmit, and Stop are blockable (return values affect the main flow); other events fire and forget. Subagent start/stop hooks are observation-only and suit telemetry.

Verify the Installation

Section titled “Verify the Installation”

In Kimi Code, run:

/plugins list
/plugins info maestria

Confirm that the plugin is enabled and its session-start skill is orchestrator. In a new session, ask the orchestrator to list its available specialists. Kimi limits each plugin system-prompt file to 32 KB; the packaged SYSTEM.md is tested against that budget.

Troubleshooting

Section titled “Troubleshooting”
Symptom Check
Plugin is missing Run /plugins list and /plugins info maestria, then restart Kimi Code
Orchestrator does not load Confirm sessionStart.skill is orchestrator and start a new session
Plugin changes do not appear Run /reload, then /new
Reviewer can edit Configure session-wide permission rules; the persona prompt is not enforcement
AgentSwarm is unavailable Verify Kimi Code v0.38.0 or later

Update

Section titled “Update”
Terminal window
npx maestria update kimi-code

Updates replace the managed package: back up local edits before updating.

Uninstall

Section titled “Uninstall”
Terminal window
npx maestria uninstall kimi-code

Or from a Kimi Code session, run /plugins remove maestria. Remove any custom [[hooks]] or [[permission.rules]] blocks from ~/.kimi-code/config.toml separately.

Next Steps

Section titled “Next Steps”