kimi-code Documentation

Kimi Code CLI — The Starting Point for Next-Gen Agents

6,233 stars TypeScript TypeScript 1 file · ~13,812 tokens
RAW Doc

Technical Documentation: MoonshotAI/kimi-code

ℹ️ Provenance: Hybrid Fusion: MoonshotAI/kimi-code (README + 9 In-Tree Chapters) · CodeWiki Reference · Recency: Active (< 180 days)

1. Project Overview & Quickstart (MoonshotAI/kimi-code)

Kimi Code CLI


Documentation · Issues · 中文

What is Kimi Code CLI

Kimi Code CLI is an AI coding agent that runs in your terminal — it can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI’s Kimi models and can also be configured to use other compatible providers.

Install

Install with the official script. No Node.js required.

  • macOS or Linux:
sh
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
  • Windows (PowerShell):
powershell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

On Windows, install Git for Windows before first launch because Kimi Code CLI uses the bundled Git Bash as its shell environment. If Git Bash is installed in a custom location, set KIMI_SHELL_PATH to the absolute path of bash.exe.

Then, run it with a new shell session:

sh
kimi --version

For npm install, upgrade, uninstall, see Getting Started.

Quick Start

Open a project and start the interactive UI:

sh
cd your-project
kimi

On first launch, run /login inside Kimi Code CLI and choose either Kimi Code OAuth or a Moonshot AI Open Platform API key. After login, try your first task:

text
Take a look at this project and explain its main directories.

Key Features

  • Single-binary distribution. Install with one command: no Node.js setup, PATH gymnastics, or global module conflicts.
  • Blazing-fast startup. The TUI is ready in milliseconds, so starting a session never feels heavy.
  • Purpose-built TUI. A carefully tuned interface, optimized end to end for long, focused agent sessions.
  • Video input. Drop a screen recording or demo clip into the chat and let the agent watch what is hard to describe in words — turn a reference clip into a LUT, a long video into a short, a screen recording into working code, and more.
  • AI-native MCP configuration. Add, edit, and authenticate Model Context Protocol servers conversationally with /mcp-config, without hand-editing JSON.
  • Rich plugin ecosystem. Install skills, MCP servers, and data sources from the marketplace or any GitHub repo, with each install's trust level surfaced up front.
  • Subagents for focused, parallel work. Dispatch built-in coder, explore, and plan subagents in isolated contexts while keeping the main conversation clean.
  • Lifecycle hooks. Run local commands at key points to gate risky tool calls, audit decisions, trigger desktop notifications, or connect to your own automation.
  • Editor & IDE integration (ACP). Drive a Kimi Code CLI session straight from Zed, JetBrains, or any Agent Client Protocol client with kimi acp.

Use it in your editor (ACP)

Kimi Code CLI speaks the Agent Client Protocol, so ACP-compatible editors and IDEs (Zed, JetBrains, …) can drive a session over stdio. Log in once, then point your editor at the kimi acp subcommand — no extra login needed.

For Zed, add this to ~/.config/zed/settings.json:

json
{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

Then open a new conversation in Zed's Agent panel. See Using in IDEs for JetBrains setup and troubleshooting, and the kimi acp reference for the full capability matrix.

Docs

Develop

Requirements: Node.js ≥ 24.15.0, pnpm 10.33.0.

sh
git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code
pnpm install
sh
pnpm dev:cli    # run the CLI in dev mode
pnpm test       # run tests
pnpm typecheck  # TypeScript check
pnpm lint       # oxlint
pnpm build      # build all packages

See CONTRIBUTING.md for the full contribution guide.

Community

Acknowledgements

Our TUI is built on top of pi-tui. We thank the authors of pi-tui for their valuable work.

License

Released under the MIT License.

2. In-Tree Documentation Chapters (MoonshotAI/kimi-code)

File: README.md

Kimi Code CLI


Documentation · Issues · 中文

What is Kimi Code CLI

Kimi Code CLI is an AI coding agent that runs in your terminal — it can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI’s Kimi models and can also be configured to use other compatible providers.

Install

Install with the official script. No Node.js required.

  • macOS or Linux:
sh
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
  • Windows (PowerShell):
powershell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

On Windows, install Git for Windows before first launch because Kimi Code CLI uses the bundled Git Bash as its shell environment. If Git Bash is installed in a custom location, set KIMI_SHELL_PATH to the absolute path of bash.exe.

Then, run it with a new shell session:

sh
kimi --version

For npm install, upgrade, uninstall, see Getting Started.

Quick Start

Open a project and start the interactive UI:

sh
cd your-project
kimi

On first launch, run /login inside Kimi Code CLI and choose either Kimi Code OAuth or a Moonshot AI Open Platform API key. After login, try your first task:

text
Take a look at this project and explain its main directories.

Key Features

  • Single-binary distribution. Install with one command: no Node.js setup, PATH gymnastics, or global module conflicts.
  • Blazing-fast startup. The TUI is ready in milliseconds, so starting a session never feels heavy.
  • Purpose-built TUI. A carefully tuned interface, optimized end to end for long, focused agent sessions.
  • Video input. Drop a screen recording or demo clip into the chat and let the agent watch what is hard to describe in words — turn a reference clip into a LUT, a long video into a short, a screen recording into working code, and more.
  • AI-native MCP configuration. Add, edit, and authenticate Model Context Protocol servers conversationally with /mcp-config, without hand-editing JSON.
  • Rich plugin ecosystem. Install skills, MCP servers, and data sources from the marketplace or any GitHub repo, with each install's trust level surfaced up front.
  • Subagents for focused, parallel work. Dispatch built-in coder, explore, and plan subagents in isolated contexts while keeping the main conversation clean.
  • Lifecycle hooks. Run local commands at key points to gate risky tool calls, audit decisions, trigger desktop notifications, or connect to your own automation.
  • Editor & IDE integration (ACP). Drive a Kimi Code CLI session straight from Zed, JetBrains, or any Agent Client Protocol client with kimi acp.

Use it in your editor (ACP)

Kimi Code CLI speaks the Agent Client Protocol, so ACP-compatible editors and IDEs (Zed, JetBrains, …) can drive a session over stdio. Log in once, then point your editor at the kimi acp subcommand — no extra login needed.

For Zed, add this to ~/.config/zed/settings.json:

json
{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

Then open a new conversation in Zed's Agent panel. See Using in IDEs for JetBrains setup and troubleshooting, and the kimi acp reference for the full capability matrix.

Docs

Develop

Requirements: Node.js ≥ 24.15.0, pnpm 10.33.0.

sh
git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code
pnpm install
sh
pnpm dev:cli    # run the CLI in dev mode
pnpm test       # run tests
pnpm typecheck  # TypeScript check
pnpm lint       # oxlint
pnpm build      # build all packages

See CONTRIBUTING.md for the full contribution guide.

Community

Acknowledgements

Our TUI is built on top of pi-tui. We thank the authors of pi-tui for their valuable work.

License

Released under the MIT License.

File: apps/kimi-code/README.md

@moonshot-ai/kimi-code

The Starting Point for Next-Gen Agents

What is Kimi Code CLI

Kimi Code CLI is an AI coding agent that runs in your terminal. It can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI's Kimi models and can also be configured to use other compatible providers.

Install

The recommended install path is the official script. It does not require Node.js to be installed first.

  • macOS / Linux:
sh
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
  • Windows (PowerShell):
powershell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

On Windows, install Git for Windows before first launch because Kimi Code CLI uses the bundled Git Bash as its shell environment. If Git Bash is installed in a custom location, set KIMI_SHELL_PATH to the absolute path of bash.exe.

Then run it with a new Terminal session:

sh
kimi --version

Alternative: npm

If you prefer npm, use Node.js 22.19.0 or later:

sh
npm install @moonshot-ai/kimi-code

Or with pnpm:

sh
pnpm add @moonshot-ai/kimi-code

For upgrade and uninstall instructions, see the Getting Started guide.

Quick Start

Open a project and start the interactive UI:

sh
cd your-project
kimi

On first launch, run /login inside Kimi Code CLI and choose either Kimi Code OAuth or a Kimi Platform API key. After login, try a first task:

text
Take a look at this project and explain the main directories.

Key Features

  • Single-binary distribution. Install with one command — no Node.js setup, no PATH gymnastics, no global module conflicts.
  • Blazing-fast startup. The TUI is ready in milliseconds, so opening a session never feels heavy.
  • Polished TUI. A carefully tuned interface designed for long, focused agent sessions.
  • Video input. Drop a screen recording or demo clip into the chat — let the agent watch instead of typing out what's hard to describe in words.
  • AI-native MCP configuration. Add, edit, and authenticate Model Context Protocol servers conversationally via /mcp-config — no hand-editing JSON.
  • Subagents for focused, parallel work. Dispatch built-in coder, explore, and plan subagents in isolated context windows; the main conversation stays clean.
  • Lifecycle hooks. Run local commands at key points — gate risky tool calls, audit decisions, fire desktop notifications, wire into your own automation.

Documentation

Repository & Issues

License

MIT

File: docs/en/guides/getting-started.md

Getting started

What is Kimi Code CLI

Kimi Code CLI is an AI agent that runs in the terminal, helping you carry out software development tasks and day-to-day terminal operations — reading and modifying code, running shell commands, searching files, fetching web pages, and autonomously planning and adjusting its next steps based on feedback as it works.

It fits scenarios such as:

  • Writing and modifying code: implementing new features, fixing bugs, completing refactors
  • Understanding a project: exploring an unfamiliar codebase and answering questions about architecture and implementation
  • Automating tasks: batch-processing files, running builds and tests, chaining multiple scripts together

The CLI is written in TypeScript, distributed via npm, and runs on Node.js.

Installation

Two installation options are available: the official install script (recommended, no pre-installed Node.js required) and a global npm install.

::: tip Before you install
Kimi Code CLI is a fully interactive TUI application. For the best visual experience, run it in a terminal with true-color and ligature support, such as Kitty or Ghostty.
:::

::: code-group

sh [macos / linux]
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
powershell [windows (powershell)]
irm https://code.kimi.com/kimi-code/install.ps1 | iex

:::

On Windows, install Git for Windows before first launch. Kimi Code CLI uses the bundled Git Bash as its shell environment; if Git Bash is installed in a custom location, set KIMI_SHELL_PATH to the absolute path of bash.exe.

The script automatically downloads the latest release, verifies the checksum, and places the kimi executable on your PATH.

npm installation

Requires Node.js 22.19.0 or later:

sh
node --version

::: code-group

sh [npm]
npm install @moonshot-ai/kimi-code
sh [pnpm]
pnpm add @moonshot-ai/kimi-code

:::

First launch

Move into your project directory and run kimi to start the interactive UI:

sh
cd your-project
kimi

To run a single instruction without entering the interactive UI, use -p:

sh
kimi -p "Take a look at this project's directory structure"

To resume the previous session, add -c:

sh
kimi -c

On first launch you need to configure an API source. In the interactive UI, enter /login to begin the login flow:

text
/login

/login opens a platform selector supporting two options:

  • Kimi Code (OAuth) — device-code flow; open the link on any device, sign in, and enter the code to authorize
  • Kimi Platform API key — enter an API key from platform.kimi.com or platform.kimi.ai

To sign out, enter /logout to clear the current credentials.

::: tip Using other AI providers
If you want to connect Anthropic, OpenAI, Google, or other providers, edit ~/.kimi-code/config.toml directly to configure the API key. See Providers and models for details. For the full reference of all config options, see Configuration files, Environment variables, and Configuration overrides.
:::

Your first conversation

Once logged in, describe a task in natural language. A good starting point is to let Kimi Code CLI familiarize itself with the project:

text
Take a look at this project's directory structure and briefly describe what each directory is for.

Kimi Code CLI automatically calls file-reading, search, and other tools to browse the relevant content before responding. Read-only operations are executed automatically by default without requiring confirmation. For operations that modify files or run shell commands, it asks for your confirmation before proceeding.

You can also describe a more concrete task directly:

text
Add a function in src/utils that converts any string to kebab-case, and add a unit test for it.

Kimi Code CLI plans the steps, modifies the code, runs the tests, and tells you what it did at each step.

::: tip Not sure what to do? Type /help
Type /help at any time to open the built-in command and keyboard shortcut panel. Use ↑/↓ to browse and Esc to close. To exit, type /exit, press Ctrl-C twice, or press Ctrl-D with the input box empty.
:::

Common commands and keyboard shortcuts

For a first-time user, the following is all you need to know:

Session commands

Command Description
/new Start a new session, clearing the current context
/sessions Browse session history and choose one to resume
/model Switch the current model
/compact Manually compress the context to free up tokens
/fork Fork the current session into an independent copy with full history (you stay in the current session)

Most-used keyboard shortcuts

Shortcut Description
Esc Interrupt streaming output / close a popup
Ctrl-C Interrupt output; press twice while idle to exit
Shift-Tab Toggle Plan mode
Ctrl-S Inject a message mid-stream without waiting for the current response to finish
Ctrl-O Collapse / expand tool output and compaction summaries

For the full list, type /help or visit Slash commands reference and Keyboard shortcuts.

Where data is stored

Kimi Code CLI stores its local data under ~/.kimi-code/ by default — config files, session records, logs, and the update cache. To move it elsewhere, point to a new path via the KIMI_CODE_HOME environment variable. For the full directory layout, see Data locations and Environment variables.

Upgrade and uninstall

After installation, verify that the executable is ready:

sh
kimi --version

Upgrade: run kimi upgrade — the CLI checks for the latest version and presents update options. Choose Install update now to upgrade based on your current install source. You can also upgrade directly via the package manager:

sh
npm install @moonshot-ai/kimi-code@latest

Uninstall: if you installed via the script, delete the kimi executable. If you installed via npm:

sh
npm uninstall -g @moonshot-ai/kimi-code

Next steps

File: docs/en/guides/goals.md

Goals

Goals keep Kimi Code working toward a defined outcome across turns. Unlike a normal prompt that says what to do next, a goal says what must become true. Use /goal when the task has a clear finish line, but the next useful step depends on what the agent learns while it works — for example, fixing a batch of failing tests or tracking down the root cause of a broken build.

Start a goal

Write the objective after /goal:

sh
/goal Fix bugs listed in the issue tracker.

Kimi Code saves the objective, sends it as the next user message, and starts goal mode. After each turn, it checks whether the goal is complete, blocked, paused, or still active.

Objectives are capped at 4000 characters; a longer objective is rejected with a warning, and the typed text is kept in the input box for editing.

Goals work best when the objective names the finish line and the evidence that proves it:

sh
/goal Fix every bug labeled checkout-regression, add or update tests for each fix, and run the checkout test suite

Avoid goals that only name a broad direction:

sh
/goal Find all bugs in this codebase.

That goal does not say what counts as success, what to inspect, or when to stop. The agent may block immediately, or keep working far longer than you expected.

When to use goals

  1. Use goals for work with a clear finish line and verifiable evidence.

    sh
    /goal Fix every failing checkout test and run the checkout test suite successfully.

    Kimi Code can inspect test output, change files, rerun checks, and decide when the goal is complete.

  2. Use goals when the task may need several turns of investigation and repair.

    sh
    /goal Find why the release build fails, fix the root cause, and verify the build passes.

    The goal describes the result, so the agent can adapt when the first clue is not the root cause.

  3. Use goals for ordered work that should continue without another prompt.

    sh
    /goal Update the feature implementation, add docs, run tests, and summarize the changed files.

    This is useful when you already know the checks or artifacts that must exist before the work is done.

When not to use goals

  1. Do not use goals for broad topics or open-ended discussions.

    ::: warning Counterexample

    sh
    /goal Greetings!

    :::

    Agents will mark the goal as complete immediately for non-goals.

  2. Do not use goals for tasks that are known to be impossible or unresolvable.

    ::: warning Counterexample

    sh
    /goal Prove 1 + 1 = 3.

    :::

    Agents will mark the goal as blocked if the goal seems impossible or unresolvable.

  3. Do not use goals with ambiguous or complicated objectives.

    ::: warning Counterexample

    sh
    /goal Create a videogame in a single HTML file.

    :::

    Agents may complete goals, but also may produce unexpected or surprising outcomes after a long time.

Manage the lifecycle

Use the same command surface to inspect or control the current goal:

Command Action
/goal or /goal status Show the current goal and its progress
/goal pause Pause the active goal without deleting it
/goal resume Resume a paused or blocked goal
/goal cancel Remove the current goal
/goal replace <objective> Replace the current goal with a new objective

A goal can stop in three ways:

  • complete: the objective is done, Kimi Code clears the goal, and the agent summarizes how it completed the work
  • paused: you paused it, interrupted the turn, resumed a session that had an active goal, or hit a model, provider, or runtime error
  • blocked: Kimi Code needs input, cannot complete the goal as stated, or reached a budget limit. When the agent blocks a goal, it writes a short message explaining why.

Write stop conditions into the objective. /goal does not have a separate stop-limit flag.

Manage goals in the web UI

The web UI shows the current goal in a strip below the conversation. Select the strip to expand or collapse its details. When a token budget is configured, the header shows its progress; goals without a token budget do not show a progress bar.

Use the strip actions to pause an active goal, resume a paused or blocked goal, or cancel the current goal. Selecting Resume starts the next goal turn so the agent continues the work. Cancellation requires confirmation because it cannot be resumed afterwards.

Queue upcoming goals

Agents sometimes complete a goal too quickly. Users can be disappointed that they can assign only one goal at a time. Many people already know the upcoming goals they want to pursue. They had to wait for the current goal to complete, open the TUI, and submit the next goal manually.

Use /goal next when you have more work ready but do not want to interrupt the current goal:

sh
/goal next Update the release notes after the tests pass

Upcoming goals are not visible to the agent while the current goal is running. When the current goal completes, Kimi Code starts the first upcoming goal in the same way as users enter /goal <objective>.

If no goal is active, /goal next <objective> starts that objective immediately. It behaves like /goal <objective> and shows a status message before the goal starts.

Manage upcoming goals interactively:

sh
/goal next manage

In the manager, use ↑ / ↓ to browse, Space to select a goal for moving, ↑ / ↓ to reorder it, E to edit, D to delete, and Esc to cancel. When editing, use Shift-Enter or Ctrl-J to add a new line, and Enter to save.

If the current goal is paused, canceled, or blocked, Kimi Code does not start the next upcoming goal. When a goal blocks and upcoming goals exist, the TUI reminds you that they wait for completion.

Use goal mode carefully

Goal mode is useful for work that can be checked with files, tests, command output, generated artifacts, or a clear written report. It is less useful for a one-off edit or a question that only needs one answer.

In manual permission mode, goal work may pause for tool call approval. For unattended work, use a permission mode that matches the risk of the repository and the commands the agent may run.

In non-interactive prompt mode, only goal creation is supported:

sh
kimi -p "/goal Fix the failing checkout test"

Prompt mode exits with code 0 when the goal completes, 3 when it blocks, and 6 when it pauses. /goal next and other management commands are TUI controls.

File: docs/en/guides/ides.md

Using Kimi Code CLI in IDEs

Kimi Code CLI supports integration into IDEs via the Agent Client Protocol (ACP), letting you use AI-assisted coding directly inside your editor.

Prerequisites

Before configuring your IDE, make sure Kimi Code CLI is installed and you have completed the login setup.

The ACP adapter is exposed as the kimi acp subcommand. The IDE launches it as a child process and communicates over stdin/stdout using JSON-RPC. Each time the IDE creates a session, the CLI reuses its existing authentication state — no need to log in again.

::: tip Path note
Child processes launched from an IDE GUI on macOS typically do not inherit the terminal shell's PATH. If kimi is not in a system directory like /usr/local/bin, use the absolute path in your IDE configuration. Run which kimi in a terminal to find the active path.
:::

Using Kimi Code CLI in Zed

Zed is a modern editor with native ACP support.

Add the following to Zed's config file at ~/.config/zed/settings.json:

json
{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

Configuration fields:

  • type: fixed value "custom"
  • command: path to the Kimi Code CLI executable. If kimi is not on PATH, use the full path (e.g. /Users/you/.local/bin/kimi).
  • args: startup arguments. The acp subcommand switches the CLI into ACP mode.
  • env: additional environment variables; usually leave this empty. Zed injects a default environment automatically.

After saving, open a new conversation in Zed's Agent panel and it will launch a Kimi Code CLI ACP subprocess using the configuration above. MCP servers declared in Zed's agent_servers section are also forwarded to the kimi side via the ACP protocol.

Using Kimi Code CLI in JetBrains IDEs

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support ACP through the AI chat plugin.

If you do not have a JetBrains AI subscription, you can enable llm.enable.mock.response in the Registry to access the AI chat panel in ACP-only scenarios. Press Shift twice and search for "Registry" to open it.

In the AI chat panel menu, click Configure ACP agents and add the following configuration:

json
{
  "agent_servers": {
    "Kimi Code CLI": {
      "command": "~/.local/bin/kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

JetBrains is strict about the command field — always use an absolute path, which you can get by running which kimi in a terminal. After saving, Kimi Code CLI will appear in the AI chat's agent selector.

Using Kimi Code CLI in Paseo

Paseo is a self-hosted orchestrator that runs and supervises agent CLIs from your desktop, web, and mobile. It connects to Kimi Code CLI over ACP, the same way an IDE does.

Pick Kimi Code CLI from Paseo's built-in ACP provider catalog, or add a custom provider in ~/.paseo/config.json:

json
{
  "agents": {
    "providers": {
      "kimi": {
        "extends": "acp",
        "label": "Kimi Code CLI",
        "command": ["kimi", "acp"]
      }
    }
  }
}

Paseo's generic ACP adapter does not drive the login flow, so complete the terminal login first (see Prerequisites) — otherwise session creation fails with Authentication required.

Troubleshooting

  • Session disconnects immediately / IDE shows "agent exited": usually a wrong command path or a missing login. Run kimi acp in a terminal first to verify — if it blocks waiting for stdin, the CLI itself is fine and the problem is in the IDE configuration; if it exits immediately with an error, follow the error message (most commonly you need to run /login).
  • IDE shows "auth required": the CLI has no usable authentication token. Exit the IDE, run kimi in a terminal to complete login, then restart the IDE.
  • MCP tools not visible: check the kimi acp reference capability table to confirm that the MCP transport type configured in your IDE is supported. The Kimi Code CLI ACP adapter currently supports http, stdio, and sse transports; acp transport MCP servers are silently dropped and a warning is written to the log.

Next steps

File: docs/en/guides/interaction.md

Interaction and input

Kimi Code CLI runs as an interactive TUI (terminal user interface) built around three components: the input box, the conversation view, and the status bar. This page covers how to enter text, paste media, navigate the approval flow, and switch between modes.

Input box basics

The input box accepts free-form text. Press Enter to send, or Shift-Enter / Ctrl-J to insert a newline. When the input box is empty, press ↑ / ↓ to browse the input history for the current working directory, including previous shell commands.

Exiting the CLI: press Ctrl-D with the input box empty, press Ctrl-C twice while idle, or type /exit. Pressing Ctrl-C or Esc during streaming output interrupts the current turn — it does not exit the program.

Pasting images and video

Kimi Code CLI supports pasting images and video directly into the input box, so you can discuss screenshots, UI mockups, architecture diagrams, or code demos without uploading or converting files first.

Video input is a distinctive Kimi Code capability — you can paste a video clip and have the model analyze its content, UI flow, or code walkthrough.

How to paste:

  • macOS / Linux: Ctrl-V
  • Windows: Alt-V

After pasting, the input box shows a placeholder that you can edit like normal text; on submit, the placeholder is replaced with the actual content. A plain-text clipboard falls back to ordinary paste. Media support depends on the current model's multimodal capabilities (image_in / video_in); it is enabled by default when you are logged in to a Kimi Code account.

Slash commands

Type / to open the completion menu — it filters as you type, Esc closes it, and unmatched input goes to the agent as a regular message. Common commands:

Command Action
/new Start a new session
/sessions Browse and resume past sessions
/compact Compact the current session's context
/undo Undo recent prompts
/model Switch the model used in the current session
/plan Toggle Plan mode (plan first, then execute)
/yolo Toggle YOLO mode (auto-approve regular tool calls)
/goal Start or manage goal mode
/help Show all commands

Active Agent Skills are also registered as slash commands (e.g. /skill:<name>). For the full list, see Slash commands reference.

File references

Type @ to trigger file-path completion; the selected path is inserted in relative form, and the agent loads the file content directly when it reads your message.

  • Where it works: both git and non-git directories; hidden paths are included, .git is excluded
  • Folder suggestions: end with /, so you can keep completing paths inside them
  • Fallback: while the fast search helper is still downloading, Kimi Code falls back to a basic filesystem scan

@ references and slash commands are two separate mechanisms: @ gives the agent file context, while / invokes built-in features or Skills.

Approval flow

When the agent calls a tool that has side effects — modifying files, running commands — the TUI displays an approval panel for your confirmation.

  • Approve: select with the arrow keys and press Enter, or press 1 / 2 / 3 to choose directly
  • Reject: Esc, Ctrl-C, or Ctrl-D
  • Approve for this session: auto-approves the same kind of call for the rest of the session
  • Permanent rules: add allow / deny entries in Configuration files

Approvals are not triggered for regular tool calls in YOLO mode, nor for writes to plan files in Plan mode.

YOLO / Auto mode

YOLO mode (/yolo) auto-approves regular tool calls, making it suitable for batch tasks you know are safe. It still asks before sensitive actions — accessing sensitive files such as .env or SSH keys, or exiting Plan mode — and the agent can still ask you questions.

Auto mode (/auto) is the fully unattended mode: every tool approval is handled automatically, including sensitive files and plan exits, and the agent never asks you questions — it decides everything on its own.

Mode switching

Plan mode

In Plan mode the agent first outputs an action plan and waits for your approval before modifying any files — useful for complex or high-risk tasks.

  • Toggle: Shift-Tab or /plan
  • Clear the current plan: /plan clear (only while idle)

After producing a plan the agent pauses for your review — you can approve it, reject it, or ask for revisions. Exiting Plan mode requires your confirmation even if YOLO mode is also active. Auto mode is the exception: plan exits are approved automatically and marked as "Auto-approved" in the transcript.

Shell mode

Shell mode lets you run terminal commands without leaving the conversation. The command output is written into the conversation context, so the agent can see the results in later turns.

  • Enter: type ! in an empty input box, or paste a command that starts with !.
  • Exit: press Backspace or Esc in an empty input box; submitting a command also returns you to normal mode automatically.
  • Run in background: while a command is running, press Ctrl+B to move it to a background task.
  • Recall previous commands: with the input box empty in shell mode, press ↑ to browse earlier shell commands; recalling one keeps you in shell mode so it runs as a command again.
  • Long output: when a finished command's output is too long, the output card collapses automatically; press Ctrl-O to expand or collapse it together with tool output.

In shell mode the input box shows a ! prompt on the left and the border turns violet. For example, you can run !gh auth login to sign in to the GitHub CLI without opening a new terminal, so Kimi can use gh afterward.

Goal mode

A goal keeps the agent working toward a defined outcome across turns — a normal prompt says what to do next, a goal says what must become true. Use /goal for tasks with a clear finish line and verifiable evidence, like fixing a batch of failing tests.

Write the objective after /goal, naming the finish line and the stop condition:

sh
/goal Fix every checkout-regression bug, add or update tests for each fix, then run the checkout test suite

Avoid broad objectives like /goal find every bug in this codebase — with no success criteria, the agent may block immediately or work far longer than expected.

Common management commands:

Command Action
/goal or /goal status Show the current goal and its progress
/goal pause / /goal resume Pause / resume the goal
/goal cancel Cancel the goal
/goal replace <objective> Replace the current goal
/goal next <objective> Queue a follow-up goal that starts when the current one completes

A goal stops in three ways: complete — achieved, cleared, and summarized; paused — you paused it, interrupted a turn, or an error occurred; blocked — the agent can't continue as stated and writes a short message explaining why. In the web UI, the goal bar below the conversation lets you pause, resume, or cancel the goal directly.

Tip: in manual permission mode a goal may stop at tool approvals; non-interactive mode only supports creating goals (kimi -p "/goal ...") — exit code 0 on complete, 3 on blocked, 6 on paused.

During streaming output

The input box remains usable while the agent is thinking or calling tools, and supports the following extra actions:

  • Ctrl-S: inject the content in the input box into the running turn immediately, without waiting for it to finish
  • Esc / Ctrl-C: interrupt the current turn
  • Ctrl-O: globally toggle the collapsed/expanded state of tool output and compaction summaries

External editor

Press Ctrl-G to send the current input content to an external editor. When you save and close, the text is written back into the input box; if you close without saving, the original content is preserved. This is handy when you need to enter large blocks of text or content with complex formatting.

Editor priority: /editor config → $VISUAL environment variable → $EDITOR environment variable. If none are set, run /editor first to choose a default.

Next steps

File: docs/en/guides/migration.md

Migrating from kimi-cli

::: info
Kimi Code CLI has gone through a major version upgrade — moving from Python/uv to Node.js, bringing a simpler install experience, faster startup, and a redesigned terminal UI. The legacy version will gradually be phased out, so we recommend upgrading as soon as possible.
:::

If you are migrating from the legacy version, follow the steps below — a single command migrates your config, MCP servers, and session history to the new version.

What's new

  • No more Python / uv: Rebuilt on Node.js — no Python environment needed, simpler to install
  • Native binary, works out of the box: Faster startup, lighter footprint
  • Redesigned terminal UI: Smoother, more responsive experience
  • Full data migration: Config, MCP servers, and session history all carry over seamlessly

How to migrate

There are two ways to migrate.

The first time you run kimi after installing kimi-code, it automatically checks whether kimi-cli data exists under ~/.kimi/. If it finds any, a migration prompt appears, and you can choose to migrate now, do it later, or never be asked again.

You can also run it manually at any time:

sh
kimi migrate

You can choose whether to migrate chat sessions as well. If you don't need the history yet, pick Config only; otherwise pick Config + N sessions to bring everything across in one go. A summary is printed at the end.

What happens during migration

What gets migrated: configuration (config.toml), MCP server configuration, input history, and whichever chat sessions you chose to migrate.

What does not get migrated: OAuth login credentials and MCP service authorizations are not copied, so you will need to run /login again and re-authorize MCP servers after migrating. kimi-cli plugins are also out of scope.

::: tip
Migration never modifies or deletes any of the old data under ~/.kimi/. kimi-cli keeps working as before, and the two do not interfere with each other. Migration can also be run repeatedly — sessions that have already been migrated are not imported again.
:::

After migration, sessions imported from kimi-cli are tagged with [imported] in the session picker so you can tell them apart from new ones.

File: docs/en/guides/sessions.md

Sessions and context

Kimi Code CLI persists every conversation as a "session" — storing message history and metadata so you can close the terminal and pick up right where you left off. This page covers how to resume sessions, manage context, and export or fork sessions.

Session storage

All sessions are saved under $KIMI_CODE_HOME/sessions/ (default: ~/.kimi-code/sessions/), grouped by working directory:

text
~/.kimi-code/
├── config.toml
├── session_index.jsonl
└── sessions/
    └── <workDirKey>/
        └── <sessionId>/
            ├── state.json
            └── agents/
                ├── main/
                │   └── wire.jsonl
                └── <subagentId>/
                    └── wire.jsonl
  • state.json: session metadata such as title and creation time.
  • agents/*/wire.jsonl: the agent event stream, used for session recovery and replay. It also carries a request trace — the tool schemas, request parameters, and MCP tool listings sent to the model — for debugging.

::: warning
Do not manually edit files inside the sessions/ directory — doing so may prevent sessions from being restored correctly.
:::

Starting and resuming sessions

Every time you run kimi directly it creates a new session. To resume a previous session, use one of the following:

Resume the most recent session in the current directory:

sh
kimi --continue

Resume a specific session by ID:

sh
kimi --session abc123

Interactively browse session history and choose one:

sh
kimi --session

::: warning
--continue and --session are mutually exclusive.
:::

Switching sessions inside the TUI

You can manage sessions without leaving the terminal. The following slash commands are available only when the agent is idle:

  • /new (alias /clear): switch to a new session, discarding the current context.
  • /sessions (alias /resume): browse and resume a previous session.
  • /fork: fork the current session (see below).
  • /title <text> (alias /rename): set a session title for easier identification; without arguments, displays the current title.

Context compression

As a conversation grows, Kimi Code CLI automatically compresses the message history when the context approaches the window limit, freeing up token space. You can also trigger compression manually at any time:

text
/compact

You can pass a hint to tell the model what to prioritize when compressing:

text
/compact Keep the discussion about database migrations

Forking a session

To explore a new direction without disrupting the current conversation, use /fork:

text
/fork

Forking does not switch you away: you stay in the original session and the conversation continues untouched. The fork is an independent copy you can switch to at any time using /sessions. A saved /goal is not copied to the fork. Start a new goal there if you want autonomous goal work.

After forking, the CLI prints a ready-to-run kimi --resume command (also copied to the clipboard) so you can enter the fork directly from a new terminal process.

Exporting a session

Use kimi export to package a session as a ZIP file — useful for sharing, archiving, or filing a bug report:

sh
kimi export <sessionId>

Omitting sessionId exports the most recent session in the current directory (with an interactive confirmation prompt; add -y to skip). Use -o to specify an output path:

sh
kimi export <sessionId> -o ~/Desktop/my-session.zip

The export includes all files in the session directory, including diagnostic logs. The global diagnostic log (~/.kimi-code/logs/kimi-code.log) is also bundled by default; add --no-include-global-log to exclude it.

You can also export from inside the TUI without leaving the interactive session:

  • /export-debug-zip: produces the same debug ZIP as kimi export.
  • /export-md (alias /export): exports the conversation as a human-readable Markdown file, suitable for sharing or archiving. Accepts an optional path argument; without one, it writes to kimi-export-<short-id>-<timestamp>.md in the current working directory.

In the web UI, /export downloads the current session as a diagnostic ZIP. It includes the persisted session data, diagnostic logs, and a bounded metadata-only logs/kimi-web.jsonl record of key browser events. Prompt text, WebSocket payloads, and console arguments are not copied into this browser log. This web command differs from the TUI /export alias above.

::: tip
Exported files may contain code, command output, and file paths that are sensitive. Review the content before sharing.
:::

Next steps

File: docs/en/guides/use-cases.md

Common use cases

This page collects typical Kimi Code CLI scenarios along with ready-to-use prompt examples — copy them as-is or adapt them to your needs.

Understanding an unfamiliar project

When taking over an unfamiliar repository, a good first step is to use kimi --plan or press Shift-Tab to enter Plan mode, so the agent outputs a research plan before touching anything:

text
Give me an overview of this repository's architecture. Specifically:
1. Where is the entry point and what happens at startup?
2. How do the main modules depend on each other?
3. How are configuration and data loaded?
Finally, draw a simple module dependency diagram.

You can also focus on a specific question:

text
How does the event loop in src/runtime work? Where do events originate, and what consumes them?
text
How is "permission approval" implemented in this project? Which files are involved, and what are the key types?

For large-scale investigations, you can have the main agent dispatch sub-agents to handle sub-tasks in parallel. See Agents and sub-agents.

Implementing a new feature

Describe the requirement and acceptance criteria clearly. For complex changes, use Plan mode to confirm the approach before execution:

text
Add a retry utility under src/utils:
- Signature: retry<T>(fn: () => Promise<T>, options): Promise<T>
- Options: maxAttempts, initialDelayMs, backoffFactor
- On failure, throw the error from the last attempt
- Add a unit test suite covering: success on first try, success after retries, and all attempts failing

If the result isn't right, just describe what you want changed — no need to edit manually:

text
The backoff calculation used a fixed value. I'd like to add some jitter to avoid the thundering-herd effect. Update the implementation and the tests.

Fixing a bug

Give the symptom, reproduction steps, and expected behavior all at once to avoid back-and-forth clarification:

text
Running npm test occasionally produces this error:

  TypeError: Cannot read properties of undefined (reading 'id')
      at SessionStore.update (src/session/store.ts:142:18)

It only appears in test cases that concurrently trigger multiple updates. Please locate the cause and fix it, then run the full test suite to confirm.

When the root cause is unclear, ask the agent to investigate before making changes:

text
User feedback: after a successful login, the first page refresh sends you back to the login page; a second refresh works fine. Please find the most likely causes first and list the most suspicious locations. I'll confirm the direction before you start making changes.

For purely mechanical tasks, you can let the agent run freely:

text
Run the test suite, fix every failing test case, then run it again to confirm everything is green.

Writing tests and refactoring

Tasks with clear boundaries and explicit acceptance criteria are particularly well-suited for the agent:

text
src/parser/markdown.ts currently has almost no tests. Please add a unit test suite covering: normal paragraphs, nested lists, code blocks, tables, blockquotes, and mixed content. Follow the testing style already used in the project.
text
Extract the repeated "read body → validate → log → respond" pattern in src/handlers into a middleware. Run the tests afterwards to make sure existing behavior is unchanged.

For multi-file refactors, use Plan mode first to confirm the approach. You can also /fork the session into an experimental branch and switch to it from /sessions — forking itself never disrupts the original session, so you can simply switch back if you don't like the result.

One-off scripts and automation

Batch file edits, statistics collection, and research comparisons can all be done with a single prompt:

text
Change all var declarations in .js files under src to const or let, preferring const where possible. Run lint once you're done to confirm.
text
Analyze the access logs in logs/ from the past 7 days. For each API path, compute the call count, p50, and p99 response times, and output the results as a Markdown table.
text
Research the main dependency injection options for TypeScript (tsyringe, inversify, awilix). Compare them across three dimensions: API style, decorator requirements, and runtime overhead. Give me a recommendation that fits on one page.

For batch tasks you know are safe, use --yolo or /yolo to skip approval prompts, or add pre-approved allowlist rules for specific tools in Configuration files.

Scheduled tasks and reminders

Inside an interactive session, you can ask the agent to set one-time reminders or recurring tasks. The agent generates a cron expression in your local timezone and re-injects the prompt into the same session when it fires:

text
Remind me at 2:30 PM to check the deployment.
text
Every weekday at 9 AM, summarize recent CI failures for me.
text
Check the production health endpoint every hour and let me know if anything looks wrong.
text
Come back in about 10 minutes and check whether the build has finished.

Scheduled tasks are bound to their session — closing the terminal is fine, and they are reloaded and continue firing when you resume the same session with kimi --session. They are not carried into brand-new sessions. Recurring tasks expire after 7 days — the agent receives a stale signal on the final trigger and decides whether to stop or renew based on your original instructions.

To see what tasks are currently pending, just ask the agent (it calls the read-only CronList tool). To cancel a task, tell the agent to remove it or reference its 8-character ID. For the full tool reference, see Scheduled tasks. The global kill switch is KIMI_DISABLE_CRON=1.

Generating and maintaining documentation

text
I just changed the interface signature in src/auth/login.ts. Please update the corresponding JSDoc, the example code in README, and any paragraphs in docs/en/guides that mention this interface.
text
For every public function under src/api that is missing a docstring, add a documentation comment following the style of the existing ones.
text
Based on the command implementations in src/cli, generate a draft command reference listing each subcommand, its arguments, and default values. Put it in docs/en/reference for me to review later.

When you need a record or a retrospective, use kimi export <sessionId> to package the session as a ZIP, or use /export-md inside the TUI to export a readable Markdown transcript.

Next steps

  • Agents and sub-agents — how to have the agent dispatch sub-tasks for parallel execution
  • Hooks — trigger local scripts at task-completion and other lifecycle points
  • Built-in tools — full reference of all tools the agent can call

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →