Plugins

A Plugin is a reviewed distribution bundle that can contribute Skills, commands, Agent Profiles, Hooks, MCP servers, executables, and output styles. Installing a Plugin adds capabilities; it does not widen a Task's workspace, permission profile, or administrator-owned security ceiling.

Your organization can distribute Plugins through an approved Marketplace, private Git source, npm registry, or local package. Kairo Code accepts compatible plugin.json manifests and installs an immutable snapshot of the reviewed bytes.

Local Host administration

Installing, activating, enabling, disabling, rolling back, or uninstalling a Plugin changes the Host's executable capability surface. Perform these actions locally on a loopback-only Host or through Desktop's SSH tunnel to such a remote Host. A JWT, API-token, paired-device, LAN, or correctly configured reverse-proxy session can inspect the bounded catalog but cannot mutate it; its Settings view is read-only. Never expose a loopback-bypass listener through a public proxy. See Only the canonical local owner can change Host-wide Plugin settings. Other identities see a read-only state and must ask the Host administrator to install or activate a Plugin.

Install and activate

Open Settings → Extensions → Plugins, select a Marketplace, Git, npm, or local source, and choose the Plugin. Before activation, review:

• the source and exact version or revision;
• newly added Skills, Agent Profiles, Hooks, commands, MCP servers, and executables; and
• whether the source is pinned to immutable bytes or can resolve differently later.

Installation, review, and activation are separate steps. Activation affects new Tasks. Existing Tasks keep the capability snapshot they started with, so a change in another window cannot silently alter a running Agent. Start a new Task when you need the newly activated Plugin.

The Plugin detail page lists retained snapshots. Selecting an older reviewed snapshot rolls back that Plugin without changing other installed Plugins. If activation fails, Kairo Code restores the previous enabled snapshot.

Author a Plugin

A minimal Plugin containing one Skill uses this layout:

my-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

.codex-plugin/plugin.json:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Adds my custom skill",
  "author": "@me",
  "license": "MIT"
}

Kairo Code also accepts .kairo-plugin/plugin.json, .claude-plugin/plugin.json, and a root plugin.json. When a source contains more than one supported manifest, precedence is Kairo, Claude, Codex, then the root file. Kairo normalizes the selected layout inside the installed artifact and does not rewrite the source directory.

Supported contribution directories are:

• skills/ for Skills in the format described in Skills;
• agents/ for Agent Profiles;
• commands/ for commands;
• hooks/ for Hooks;
• bin/ for Plugin executables; and
• output-styles/ for output styles.

MCP servers are not discovered from an mcp/ directory. Define them either in a root-level .mcp.json file whose top-level object is mcpServers, or in the selected Plugin manifest's mcpServers field. When both sources define the same server name, the manifest value wins.

Agent Profiles (agents/*.md)

Each Markdown file under agents/ defines one reusable Agent Profile. A usable Profile must resolve to a non-empty name, a non-empty delegation description, and non-empty instructions. The filename without .md supplies the default name, so name may be omitted only when that filename is the intended name. Put description in YAML frontmatter and the instructions in the Markdown body. Kairo skips a Profile whose resulting name, description, or instruction body is blank.

---
name: code-reviewer
description: Reviews code diffs and reports findings without modifying the workspace
tools:
  - read
  - grep
---
Review correctness, security, and missing verification. Return findings only.

Plugin Profiles use the same execution ceilings as workspace Profiles, so the full field contract remains defined in Create a Profile:

Field	Requirement or default	Purpose
name	Required; filename without .md is the default	Profile name inside the Plugin namespace
description	Required and non-empty	Delegation hint shown to the main Agent
Markdown body	Required and non-empty	Instructions supplied to the delegated Agent
model	Inherit parent	Optional model override
model_reasoning_effort	Inherit parent	Optional reasoning tier supported by the selected model
sandbox_mode	Inherit parent	read-only or workspace-write; can narrow but never widen the parent
tools	Inherit parent	Optional tool allowlist; unknown tools are dropped
skills	Inherit parent	Omit to inherit, use [] to disable all, or list the allowed intersection
mcp_servers	Inherit parent	The same three-state ceiling for MCP servers

After activation, Kairo Code registers the profile under a qualified name such as my-plugin:code-reviewer. The main Agent can invoke it through the same task delegation tool used for built-in and workspace Agent Profiles. Each invocation is a task-scoped Subagent; installing the Plugin does not create a persistent Team or a second orchestration system.

Refer to the Plugin root

Use ${KAIRO_PLUGIN_ROOT} inside Plugin files when a command or MCP definition needs the installed Plugin location:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${KAIRO_PLUGIN_ROOT}/server.js"]
    }
  }
}

Use that object as the entire root-level .mcp.json file. The same mcpServers object may instead be placed in plugin.json; the manifest also accepts a path to a Plugin-root-relative JSON file. Remote HTTP/SSE definitions use url (and optional type and headers) in place of command and args.

An imported source with an explicit .claude-plugin/plugin.json may contain the three legacy ${CLAUDE_*} Plugin placeholders. The upstream loader rewrites them in memory to the corresponding KAIRO_* names before returning a manifest; Kairo-native and manifestless sources fail closed if those placeholders remain.

Storage and rollback

Under the effective Kairo Code data directory, Plugin data is separated by purpose:

• plugins/cache/ contains downloaded source caches;
• plugins/artifacts/<name>/<version>/<sha256>/<name>/ contains immutable runtime snapshots; and
• plugins/data/<plugin-name>/ contains runtime-writable Plugin data.

The runtime always references the content-addressed artifact, not the downloader cache or original local source directory. Editing a local source therefore does not silently modify an installed Plugin. Uninstall removes runtime registration but retains immutable artifacts for deduplication and later rollback.

Marketplace sources

Marketplace sources have an explicit CURATED, REVIEWED, or COMMUNITY trust tier and must use a credential-free HTTPS catalog URL. Removing a Marketplace source does not uninstall Plugins or Skills already installed from it.

Git catalogs may pin a branch, tag, or full commit SHA. Kairo Code shows the resolved commit and keeps the last verified snapshot available if the remote is temporarily unavailable. A full SHA provides immutable installation coordinates; a branch or tag remains installable, but review marks it as mutable because a later reinstall may resolve to different bytes.

The Marketplace view records the last check, last successful refresh, sanitized failure reason, and currently served Git commit. A failed refresh marks the source degraded while preserving the last successfully verified catalog.