What Are Subagents in Kimi Code? Understanding Coder, Explore, and Plan Agents

Subagents in Kimi Code are autonomous worker units spawned by a parent agent to perform specialized tasks like exploring codebases or executing edits, returning results via structured XML-like transcript fragments defined in the MoonshotAI/kimi-code protocol.

The MoonshotAI/kimi-code repository implements a sophisticated hierarchical agent architecture where complex software engineering tasks are decomposed across multiple specialized processes. Understanding what subagents are in Kimi Code—and how the coder, explore, and plan variants function—provides essential insight into the system's modular execution model.

What Are Subagents in Kimi Code?

Kimi Code treats every autonomous execution unit as an Agent. When an agent requires delegated work—such as scanning a codebase, running diagnostics, or generating implementation plans—it spawns a subagent.

Internally, subagents are represented as tasks with kind: 'subagent', defined in packages/transcript/src/model/task.ts. Their lifecycle emits a strict protocol of events including subagent.spawned, subagent.started, subagent.suspended, subagent.completed, and subagent.failed, all declared in packages/protocol/src/events.ts.

The parent agent subscribes to the subagent’s transcript stream, allowing the main turn to embed the sub-run’s output as an XML-like <subagent …> element. This mechanism, implemented in packages/agent-core/src/session/subagent-host.ts, creates a hierarchical communication channel between parent and child agents.

How Coder and Explore Agents Function

The agent tool exposed in packages/agent-core/src/tools/agent.ts accepts a subagent_type parameter that determines which specialized logic executes.

The Explore Subagent

Setting subagent_type to "explore" creates a foreground subagent that loads specified source files and uses Kimi’s code-understanding capabilities to produce concise reports. For example, the subagent might analyze imports and report “dependencies are stable.” The result returns as a <subagent …> fragment that the parent embeds in its own output.

Tests in packages/agent-core/test/tools/agent.test.ts verify that the tool description correctly exposes subagent_type="explore" and validates that summaries appear in parent output.

import { Klient } from '@moonshot-ai/klient';

const client = new Klient({ url: 'http://127.0.0.1:58627' });

await client.runTool('agent', {
  subagent_type: 'explore',
  item: 'src/components/Button.tsx',
});

The client receives a structured fragment:

<subagent agent_id="agent-explore-1" item="src/components/Button.tsx" outcome="completed">
  The button component imports React and defines a styled‑component.
</subagent>

The Coder Subagent

When subagent_type is set to "coder", the subagent executes specific file manipulation or code generation tasks. This type handles the actual implementation work delegated by plan agents or parent turns, performing edits in isolated execution contexts while maintaining separation from the parent agent's state.

How the Plan Agent Orchestrates Subagents

The plan agent activates when an agent enters plan mode and invokes the plan tool from packages/agent-core/src/tools/plan.ts.

This tool generates structured, revisable plans stored with plan_revision fields in the task model (packages/transcript/src/model/task.ts). Each plan step can delegate execution to specialized subagents—typically using subagent_type="coder"—allowing individual steps to run in isolated contexts while the main plan remains visible in the transcript. Plan turns receive a distinctive plan badge, and revisions persist across conversation turns.

const plan = await client.runTool('plan', {
  description: 'Refactor the authentication flow',
  steps: [
    { action: 'explore', target: 'src/auth/**' },
    { action: 'rewrite', target: 'src/auth/login.ts' },
  ],
});

Subagent Execution Modes and Resume Capabilities

Subagents operate in two distinct modes. Foreground subagents block the parent turn until completion, while background subagents detach via the background manager, allowing parallel execution.

The resume logic in subagentHost.resume (from packages/agent-core/src/session/subagent-host.ts) enables re-attaching a suspended subagent using only its agent_id, without requiring the original subagent_type argument. Validation in packages/agent-core/src/tools/agent.ts enforces this resume behavior, ensuring seamless continuation of interrupted workflows.

await client.runTool('agent', {
  resume: plan.subagents?.[0]?.agent_id,
});

Summary

• Subagents in Kimi Code are hierarchical worker units defined with kind: 'subagent' that handle delegated tasks via the protocol events defined in packages/protocol/src/events.ts.
• The explore subagent type scans codebases and returns structured summaries, while the coder type performs implementation work.
• The plan agent generates revisable workflows that orchestrate subagent execution through the plan tool and plan_revision tracking in packages/transcript/src/model/task.ts.
• Results communicate through XML-like <subagent …> elements managed by the subagent host in packages/agent-core/src/session/subagent-host.ts.
• Foreground execution blocks the parent, while background execution enables parallelism, with robust resume capabilities via agent_id.

Frequently Asked Questions

What is the difference between foreground and background subagents in Kimi Code?

Foreground subagents run synchronously, blocking the parent agent until they emit subagent.completed or subagent.failed. Background subagents detach immediately via the background manager, allowing the parent to continue processing while the child executes independently.

How does the resume mechanism prevent duplicate subagent type declarations?

When resuming via subagentHost.resume, the system validates the agent_id against existing suspended sessions. Because the subagent’s type was established during initial spawning (subagent_type), the resume call in packages/agent-core/src/tools/agent.ts only requires the agent_id, eliminating redundant parameter passing.

Can a parent agent spawn multiple subagents simultaneously?

Yes. According to the architecture in packages/agent-core/src/session/subagent-host.ts, agents can spawn numerous foreground and background subagents. The transcript system aggregates results from multiple <subagent …> fragments, though each requires a unique agent_id for tracking.

Are subagent results immutable once embedded in the transcript?

Yes. Once a subagent completes and the parent embeds the <subagent agent_id="..." outcome="completed"> fragment, that record becomes part of the permanent transcript history. Subsequent modifications require spawning new subagents or creating revised plan steps, as the original XML-like elements remain frozen for audit trails.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}