How to Set Up and Use Subagents Like Coder, Explore, and Plan for Parallel Work

Kimi Code enables parallel task execution through specialized subagents—lightweight agents that run isolated tasks concurrently within a single session.

The MoonshotAI/kimi-code repository implements a powerful subagent architecture that allows the main agent to delegate work to specialized workers. By configuring the built-in coder, explore, and plan subagents, you can execute read-only exploration, code generation, and architectural planning in parallel without blocking the primary workflow.

Understanding the Three Built-in Subagents

Kimi Code provides three default subagent profiles optimized for distinct operational modes:

• explore – A read-only reconnaissance agent designed for fast repository traversal. It utilizes Glob, Grep, Read, Bash, WebSearch, and FetchURL tools to gather information without modifying files.
• coder – A write-oriented implementation focused on code generation and modification. It employs Write, Edit, Bash, and Read tools to create and refactor source files.
• plan – A high-level strategic agent that breaks down complex goals into actionable outlines. It uses Write, Read, and read-only Bash operations to produce structured task lists.

Where Subagent Profiles Are Defined

Profile Configuration Files

All subagent behaviors are defined as YAML profiles stored in packages/agent-core/src/profile/default/. Each file specifies the available tools, system prompts, and operational constraints:

• Explore profile: packages/agent-core/src/profile/default/explore.yaml
• Coder profile: packages/agent-core/src/profile/default/coder.yaml
• Plan profile: packages/agent-core/src/profile/default/plan.yaml

Profile Loading Mechanism

At runtime, the engine loads these YAML definitions through packages/agent-core/src/profile/load.ts. This module reads the raw profile strings and constructs the DEFAULT_AGENT_PROFILES constant exported from packages/agent-core/src/profile/default.ts. When spawning a subagent, the system references this registry to instantiate the correct behavior set.

How to Spawn Subagents for Parallel Execution

The Sub-Agent Host Implementation

When a tool request specifies kind: "agent" with a subagentType parameter, the subagent host at packages/agent-core/src/session/subagent-host.ts manages the lifecycle. The host performs three critical operations:

1. Looks up the requested profile name (coder, explore, or plan) in DEFAULT_AGENT_PROFILES.
2. Assigns a unique identifier (sub-<n>) and creates a new Task of kind subagent in the transcript.
3. Initializes a dedicated turn for the subagent, wiring its transcript and event handlers.

Task Tracking and Concurrency Model

The parallel execution model relies on the transcript system defined in packages/transcript/src/model/task.ts. Each subagent run generates a Task with TaskKind = 'subagent', enabling the engine to track multiple concurrent operations.

The architecture supports true parallelism: subagents operate on independent turns and can issue multiple tool calls simultaneously (such as concurrent Glob and Grep operations). The main agent continues processing while subagents execute, receiving completion events via subagent.completed or subagent.failed payloads containing concise result summaries.

Practical Implementation Examples

Setting Up the Explore Subagent

Use the Node SDK to spawn an explore subagent for repository analysis. The client automatically handles the agent tool invocation and subagent lifecycle events:

import { KimiClient } from '@moonshot-ai/kimi-code-sdk';

const client = new KimiClient();
const session = await client.createSession({ id: 'demo-session' });

// Request triggers the main agent to spawn an explore subagent
await session.sendMessage({
  role: 'user',
  content: 'Find all TypeScript files that import `zod`.'
});

session.on('subagent.completed', (ev) => {
  console.log('Explore result:', ev.output);
});

Under the hood, packages/agent-core/src/session/subagent-host.ts instantiates the agent using the explore profile. The subagent executes parallel Glob and Grep calls—each represented as separate tasks in the transcript—and returns the file list through the completion event.

Running Parallel Coder Subagents

For bulk refactoring operations, spawn multiple coder subagents simultaneously to process files in parallel:

const files = ['src/a.ts', 'src/b.ts', 'src/c.ts'];

// Launch independent coder subagents for each file
for (const file of files) {
  await session.sendMessage({
    role: 'user',
    content: `Rewrite ${file} to use the new logging API.`
  });
}

// Aggregate results as subagents complete
session.on('subagent.completed', ({ subagentId, output }) => {
  console.log(`Coder ${subagentId} finished:`, output);
});

Each coder instance operates in isolation, issuing Write and Edit tools independently. The main agent receives individual summaries from packages/transcript/src/model/task.ts entries and determines whether additional coordination is required.

Using the Plan Subagent for Task Breakdown

Initialize the plan subagent to generate structured implementation roadmaps before executing code changes:

await session.sendMessage({
  role: 'user',
  content: 'Create a step-by-step plan to add OAuth support to the CLI.'
});

session.on('subagent.completed', ({ output }) => {
  console.log('Generated plan:\n', output);
});

The plan subagent returns a structured task list that the main agent can feed into subsequent coder subagent batches, creating a pipeline from architecture to implementation.

Summary

Setting up parallel subagents in Kimi Code involves leveraging the default profile system and SDK tooling to orchestrate concurrent workflows:

• Subagents are defined in packages/agent-core/src/profile/default/*.yaml and loaded via packages/agent-core/src/profile/load.ts.
• The subagent host in packages/agent-core/src/session/subagent-host.ts manages instantiation and lifecycle events.
• Each subagent runs as a distinct Task (TaskKind = 'subagent') tracked in packages/transcript/src/model/task.ts.
• The coder, explore, and plan profiles provide specialized tool sets for write operations, read-only exploration, and architectural planning respectively.
• Parallel execution is achieved by spawning multiple subagents, each receiving independent turns and tool execution contexts.

Frequently Asked Questions

What is the difference between the coder and explore subagents?

The coder subagent is optimized for write operations, equipped with Write and Edit tools to modify source code, while the explore subagent is strictly read-only, utilizing Glob, Grep, and Read tools for fast repository traversal. According to the profile definitions in packages/agent-core/src/profile/default/, the explore agent cannot modify files, making it safe for parallel reconnaissance tasks while the main agent continues working.

How does Kimi Code handle concurrent subagent execution?

The engine implements a non-blocking concurrency model where each subagent receives its own turn and transcript context as managed by packages/agent-core/src/session/subagent-host.ts. Subagents can issue multiple tool calls simultaneously, and their progress is tracked as separate Task entries in packages/transcript/src/model/task.ts. The main agent processes subagent.completed events asynchronously without waiting for individual subagents to finish.

Can I customize the default subagent profiles?

Yes, the profile system loads YAML configurations from packages/agent-core/src/profile/load.ts, which constructs DEFAULT_AGENT_PROFILES. You can modify the existing coder.yaml, explore.yaml, or plan.yaml files in packages/agent-core/src/profile/default/, or extend the loading mechanism to include custom profile definitions that inherit from these base configurations.

How do subagents communicate results back to the main agent?

When a subagent completes its turn, it emits a subagent.completed event containing a concise summary of its output. The main agent receives this payload through the SDK or RPC interface and incorporates it into subsequent prompts. If a subagent fails, it emits subagent.failed with error details, allowing the main agent to decide whether to retry, escalate, or proceed with partial results.

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