Installation & Setup

@maestria/kimi-code is a declarative Kimi Code plugin - a manifest, skills, native slash commands, and a system-prompt contribution. The plugin is loaded by Kimi Code at session start, and the orchestrator skill auto-injects the methodology.

Prerequisites

• Kimi Code v0.38.0+ - the verified version for native plugin systemPromptPath, plugin commands, and the current plugin registry. Older versions may load the skills-only subset, but are outside the supported boundary.
• Node.js 18+ - required for npm pack used by the CLI to install the plugin.

Installation via CLI (Recommended)

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

npm

# Install for this platform
npx maestria install kimi-code

pnpm

# Install for this platform
pnpx maestria install kimi-code

yarn

# Install for this platform
yarn dlx maestria install kimi-code

npm

# Verify installation
npx maestria status

pnpm

# Verify installation
pnpx maestria status

yarn

# Verify installation
yarn dlx maestria status

Additional setup required

The CLI installs and registers the plugin without overwriting global instructions. You still need to add the recommended hooks and permission rules to ~/.kimi-code/config.toml. See the manual setup section below for the complete steps.

Alternative: Manual setup

1. Install the plugin

   The plugin is distributed via npm. The maestria CLI downloads and extracts it directly:

   npm

   npx maestria install kimi-code

   pnpm

   pnpx maestria install kimi-code

   yarn

   yarn dlx maestria install kimi-code

   This runs npm pack @maestria/kimi-code@latest, extracts the tarball into a temporary directory, and installs it through Kimi’s native plugin manager.

   Alternatively, you can install directly from npm with the same commands used internally:

   npm pack @maestria/kimi-code@latest --pack-destination /tmp
   mkdir -p /tmp/maestria-kimi-code
   tar -xzf /tmp/maestria-kimi-code-*.tgz -C /tmp/maestria-kimi-code --strip-components=1
   # In Kimi Code, run: /plugins install /tmp/maestria-kimi-code
   rm -f /tmp/maestria-kimi-code-*.tgz

2. Verify the plugin (REQUIRED)

   Kimi owns the install record and managed copy. Verify both through the native plugin manager:

   /plugins list
   /plugins info maestria

   Caution

   SYSTEM.md is contributed through the plugin’s native systemPromptPath. Kimi limits each plugin system-prompt file to 32 KB; the packaged file is tested against that limit.

3. Add lifecycle hooks to config.toml (recommended)

   Open ~/.kimi-code/config.toml and add the following [[hooks]] blocks. These block destructive bash commands, inject a per-turn orchestrator reminder, and observe compaction cycles.

   # Block destructive bash commands
   [[hooks]]
   event = "PreToolUse"
   matcher = "Bash"
   command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
   timeout = 5
   
   # Per-turn orchestrator reminder
   [[hooks]]
   event = "UserPromptSubmit"
   matcher = ""
   command = "echo 'Maestria active: delegate via the orchestrator skill. Prefer adventurer for recon, architect for design, builder for implementation, diagnose for bugs, reviewer for QA, writer for docs, planner for multi-phase work.'"
   timeout = 5
   
   # Observe compaction cycles (observation-only)
   [[hooks]]
   event = "PreCompact"
   matcher = ".*"
   command = "echo \"compact start: $(date -Is)\" >> ~/.kimi-code/compact.log"
   timeout = 5
   
   [[hooks]]
   event = "PostCompact"
   matcher = ".*"
   command = "echo \"compact end:   $(date -Is)\" >> ~/.kimi-code/compact.log"
   timeout = 5

   Save the companion script as ~/.kimi-code/hooks/block-dangerous-bash.mjs:

   let input = '';
   process.stdin.on('data', (chunk) => {
     input += chunk;
   });
   process.stdin.on('end', () => {
     const payload = JSON.parse(input);
     const command = payload.tool_input?.command ?? '';
     if (command.includes('rm -rf')) {
       console.error('Dangerous command detected, blocked');
       process.exit(2);
     }
   });

4. Optional: add review-only permission rules

   These rules apply to the whole session

   By default, the 3 built-in Kimi Code subagents have full tool access. The reviewer and adventurer personas describe safety constraints in their SKILL.md text (“do not edit files”, “read-only Bash”), but those constraints are advisory only. The deny rules below apply at session scope, so they also block Write/Edit for builder and writer. Use them only for a review-only session, not as a permanent general-purpose configuration.

   Add the following to ~/.kimi-code/config.toml:

   # === Builder (coder) - read-only git + test commands ===
   # 6 separate rules because each `pattern` matches one command.
   # scope = "session-runtime" applies to the current session only.
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(git status*)"
   scope = "session-runtime"
   reason = "Builder: read-only git status"
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(git diff*)"
   scope = "session-runtime"
   reason = "Builder: read-only git diff"
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(git log*)"
   scope = "session-runtime"
   reason = "Builder: read-only git log"
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(npm test*)"
   scope = "session-runtime"
   reason = "Builder: run npm tests"
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(pnpm test*)"
   scope = "session-runtime"
   reason = "Builder: run pnpm tests"
   
   [[permission.rules]]
   decision = "allow"
   pattern = "Bash(npx tsc*)"
   scope = "session-runtime"
   reason = "Builder: run TypeScript type check"
   
   # === Review-only session - deny Write/Edit for every coder subagent ===
   # Do not use these session-wide denies while running builder or writer work.
   
   [[permission.rules]]
   decision = "deny"
   pattern = "Write"
   scope = "session-runtime"
   reason = "Review-only session: block all Write tools"
   
   [[permission.rules]]
   decision = "deny"
   pattern = "Edit"
   scope = "session-runtime"
   reason = "Review-only session: block all Edit tools"

   The scope field controls temporal granularity (turn-override, session-runtime, project, user) - it is not per-subagent granularity. Subagent tool lists come from the hardcoded profile (coder/explore/plan), not from per-agent rules. These rules provide session-wide tool enforcement for a review-only session; they cannot safely enforce reviewer boundaries while builder or writer work runs in the same session.

5. Reload plugins and start a new session

   Plugin changes only take effect in new sessions. After installing, run:

   /reload
   /new

6. Verify

   In the fresh session, ask:

   “Review these 5 files for security issues: src/auth.ts, src/api.ts, src/db.ts, src/routes.ts, src/middleware.ts”

   The orchestrator should:

   1. Auto-load (via sessionStart.skill).
   2. Identify the work as ≥3 uniform items → use AgentSwarm with the reviewer persona.
   3. Dispatch a swarm across the 5 files.

   If the orchestrator starts writing code directly, check /plugins list and confirm the session-start skill loaded.

7. Use native workflow commands (optional)

   Kimi namespaces commands contributed by plugins:

   /maestria:fein
   /maestria:sonar
   /maestria:blitz

Troubleshooting

Orchestrator not loading

• Check /plugins list - maestria should appear with enabled: true.
• Check /plugins info maestria for manifest diagnostics and confirm sessionStart.skill is orchestrator.
• Restart Kimi Code completely (not just the session).

AgentSwarm not available

• Use Kimi Code v0.38.0+; older releases are outside the verified support boundary for this package.

System prompt gets truncated

• The 32 KB plugin system-prompt budget is enforced by Kimi Code. Keep long detail in specialist SKILL.md files, loaded on demand via the Skill tool.

Updating

To update via the maestria CLI:

npm

npx maestria update kimi-code

pnpm

pnpx maestria update kimi-code

yarn

yarn dlx maestria update kimi-code

To pin to a specific version:

npm

npx maestria update kimi-code --version 0.5.2

pnpm

pnpx maestria update kimi-code --version 0.5.2

yarn

yarn dlx maestria update kimi-code --version 0.5.2

Alternative: Manual update

The CLI uses npm to fetch the latest version. The same commands work manually:

npm pack @maestria/kimi-code@latest --pack-destination /tmp
mkdir -p /tmp/maestria-kimi-code
tar -xzf /tmp/maestria-kimi-code-*.tgz -C /tmp/maestria-kimi-code --strip-components=1
# In Kimi Code, run: /plugins install /tmp/maestria-kimi-code
rm -f /tmp/maestria-kimi-code-*.tgz

Caution

Updates overwrite any local edits to the bundled SKILL.md files. If you have customized them, fork the repository or back up your changes before re-installing.

Uninstalling

npm

npx maestria uninstall kimi-code

pnpm

pnpx maestria uninstall kimi-code

yarn

yarn dlx maestria uninstall kimi-code

# or from a Kimi Code session:
/plugins remove maestria

Optionally remove the [[hooks]] and [[permission.rules]] blocks from ~/.kimi-code/config.toml.

Next Steps

• Quick Start - Your first session with the plugin
• Skill Reference - Detailed documentation for each skill