Kimi CLI Agents Explained: Built-in and Custom AI Agents, Sub-agents, and Tools

Forum topic · ✨步子哥 · 2026-01-27

Summary

Kimi CLI, a command-line AI assistant tool by Moonshot AI, organizes agent behavior around three building blocks: agents, system prompts, and tools. Two built-in agents ship with the tool: the default agent, which enables tools like Task, SetTodoList, Shell, ReadFile, Glob, Grep, WriteFile, StrReplaceFile, SearchWeb, and FetchURL; and the experimental okabe agent, which additionally enables SendDMail for delayed-message checkpoint rollbacks. Custom agents are defined in YAML files loaded via --agent-file, supporting an extend field for inheritance and tool exclusion, system_prompt_path pointing to Markdown templates with variables such as ${KIMI_NOW} and ${KIMI_WORK_DIR}, and custom parameters via system_prompt_args. Sub-agents can be declared statically with path and description, or created dynamically at runtime through the CreateSubagent tool. Sub-agents run in isolated contexts, enabling parallelism and preventing context pollution. Safety is enforced via working-directory boundaries and per-action user approval for shell commands, file writes, edits, and MCP calls, along with limits on file sizes, line counts, and glob patterns. This article is an English translation and structured summary of a Chinese forum post describing the agent system of Kimi CLI, including its built-in tools, prompt templating, sub-agent architecture, and security model.

Introduction

Kimi CLI is a command-line AI assistant built by Moonshot AI that connects local files and cloud intelligence. Its power comes from an agent system: an agent defines the AI's behavior through a system prompt, a set of available tools, and sub-agents. Agents are selected with --agent (e.g., kimi --agent okabe) or loaded from YAML files with --agent-file /path/to/my-agent.yaml.

Built-in Agents

default: enables Task, SetTodoList, Shell, ReadFile, ReadMediaFile, Glob, Grep, WriteFile, StrReplaceFile, SearchWeb, and FetchURL — covering task management, file operations, and web search.
okabe (experimental): everything in default plus SendDMail, used to send delayed messages to checkpoint IDs for rollback-style workflows. It is experimental to encourage testing new prompts and tool combinations.

Custom Agents in YAML

A custom agent file uses version: 1 and an agent block with:

name (optional when inheriting)
system_prompt_path — path to a Markdown template file
system_prompt_args — custom template parameters
tools — list in module:ClassName format, e.g., kimi_cli.tools.shell:Shell
exclude_tools — remove inherited tools (e.g., SearchWeb, FetchURL)
subagents — sub-agent definitions
extend — inherit from default, okabe, or another YAML file via relative path, merging system_prompt_args while overriding other fields

System Prompt Templates

Prompt files are Markdown templates using ${VAR} syntax. Built-in variables include ${KIMI_NOW} (current time, ISO), ${KIMI_WORK_DIR} (working directory), ${KIMI_WORK_DIR_LS} (directory listing), ${KIMI_AGENTS_MD} (AGENTS.md contents if present), and ${KIMI_SKILLS} (loaded skills). Custom args defined in system_prompt_args (e.g., MY_VAR: "value") can be referenced as ${MY_VAR}.

Sub-agents

Static sub-agents are declared in the subagents block with path (relative) and description (e.g., a coder and a reviewer). Sub-agent files typically extend the main agent, add role descriptions via system_prompt_args, and exclude the Task tool to avoid nested loops. The main agent launches them via the Task tool with description, subagent_name, and prompt. Each sub-agent runs in an isolated context (its own conversation history), returns results when done, and enables parallel task handling.

The CreateSubagent tool (not enabled by default; add to tools manually) lets the AI define new sub-agent types at runtime with a unique name and a system_prompt describing its role and boundaries.

Built-in Tools

Task: dispatch a sub-agent; the prompt must contain all needed information since the sub-agent cannot see the main context.
SetTodoList: track todos with titles and pending/in_progress/done status.
Shell: execute commands (bash/zsh or PowerShell per OS); requires approval; timeout defaults to 60s, max 300s.
ReadFile: read text files, capped at 1000 lines / 2000 characters; absolute paths required outside the working directory.
ReadMediaFile: read images/video up to 100MB, only if the model supports it.
Glob: pattern matching (e.g., *.py), max 1000 items; patterns cannot start with .

Grep: regex content search with path/glob/type filters, output modes (files_with_matches), context flags (-B/-A/-C), -n, -i, multiline, and head_limit.

WriteFile: write files (absolute path; overwrite or append mode); requires approval.

StrReplaceFile: string-replacement edits (old, new, replace_all); requires approval.

SearchWeb: web search; limit defaults to 5, max 20; optional include_content.

FetchURL: fetch a URL and return the main text.

Think: record reasoning for complex tasks.

SendDMail: send a delayed message to a checkpoint (id >= 0).

CreateSubagent**: define new sub-agent types at runtime.

Safety Boundaries

Tool operations are constrained to the working directory (absolute paths required outside). Writes, edits, Shell execution, and MCP calls require per-action user approval — a safety valve preventing unintended actions. Limits on glob patterns, file sizes, and line counts prevent resource abuse, balancing capability with safety.

Conclusion

Kimi CLI's agent system evolves from built-in defaults to fully custom YAML configurations, from static sub-agent declarations to runtime creation — an ecosystem where agents, tools, and safety boundaries work together to make a reliable local AI assistant.

---

*Translated and edited from a Chinese forum post on zhichai.net, based on the Kimi CLI official documentation (Moonshot AI).*