How to Use Kimi Code: Install, Login, Commands, and the kimi-cli Trap

What is Kimi Code?

Kimi Code is the official terminal coding agent from Moonshot AI, the company behind the Kimi models. It is open source under the MIT license, written in TypeScript, and invoked with the kimi command. You run it inside a project folder, describe what you want, and it plans, edits files, and executes shell commands with your approval.

Under the hood it runs on Kimi K3, the model Moonshot released on July 16, 2026: a 2.8 trillion parameter Mixture of Experts model with a context window of up to 1,048,576 tokens and native vision. K3 always reasons before answering, which makes it strong on hard multi-step work. If you want the model details and what they cost, the plans and pricing guide goes deep on that.

If you already use Claude Code, Kimi Code will feel familiar on purpose. Its tools carry the same names (Bash, Read, Write, Edit), it follows the AGENTS.md convention for project instructions, and its MCP configuration is compatible with the .mcp.json file Claude Code already reads. The Kimi Code vs Claude Code comparison covers exactly where they differ.

Before you install: the two kimis trap

Moonshot has shipped two terminal agents, and both of them install a binary called kimi. Getting this wrong is the number one way people end up confused, and most posts about Kimi Code never mention it.

• kimi-cli (legacy): the original Python agent, in the MoonshotAI/kimi-cli repository, with its data under ~/.kimi/. It is being wound down, but it has years of stars and blog posts pointing at it, so search results and AI assistants still send people there.
• Kimi Code (current): the TypeScript agent this guide is about, in the MoonshotAI/kimi-code repository, with its data under ~/.kimi-code/. This is the one under active development.

The package names make it worse, because they are crossed. The PyPI package called kimi-code is an empty meta-package that installs the legacy Python agent. The real Kimi Code lives on npm as @moonshot-ai/kimi-code. So installing "kimi-code" from pip gets you the old product, and the new product comes from npm or from the official install script.

# Check which kimi you actually have
kimi --version

# 0.x  -> Kimi Code, the current TypeScript CLI (this guide)
# 1.4x -> kimi-cli, the legacy Python agent

How to install Kimi Code

The recommended path is the official install script, which does not require Node.js. It downloads the latest release, verifies the checksum, and puts the kimi executable on your PATH (the binary itself lands in ~/.kimi-code/bin/).

# macOS and Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

# Windows (PowerShell)
irm https://code.kimi.com/kimi-code/install.ps1 | iex

If you prefer a package manager, Kimi Code is on npm. This route needs Node.js 22.19.0 or later:

# Check your Node version first
node --version

# npm
npm install -g @moonshot-ai/kimi-code

# or pnpm
pnpm add -g @moonshot-ai/kimi-code

Either way, open a fresh terminal afterward and confirm the install with kimi --version. You should see a 0.x version. To update later, run kimi upgrade and the CLI checks for the latest version itself, or reinstall with npm install -g @moonshot-ai/kimi-code@latest.

First run and logging in

Start Kimi Code inside a project folder by typing kimi. On first run, use the /login command inside the TUI. It opens a platform selector with two options:

• Sign in with your Kimi account: an OAuth device-code flow. Kimi Code shows you a link, you confirm in the browser, and the CLI picks the session up. This is the route for Kimi subscription plans.
• API key: paste a key from the Moonshot platform if you pay per token instead of subscribing.

Credentials are stored locally under ~/.kimi-code/. Once you are logged in, every new kimi session in any folder reuses them. Inside the TUI, /usage shows where you stand against your quota, which on subscriptions works as a weekly allowance plus a rolling 5-hour window.

Everyday usage: the commands and flags that matter

Day to day you will live inside the interactive session, with a handful of flags for starting, resuming and automating:

# Start a session in the current project
kimi

# Continue the last session in this folder
kimi --continue        # or: kimi -c

# Resume a specific session by id
kimi --session <id>

# One-shot headless run (no TUI), like claude -p
kimi -p "explain what this repo does"

# Modes
kimi --plan     # plan before acting
kimi --auto     # more autonomy, still gated
kimi --yolo     # auto-approve everything (careful)

A few input details worth knowing: Enter sends your message, and Ctrl-J or Alt-Enter inserts a newline. /title names the current session, which makes it much easier to find later. And if you resume a session while passing --yolo, --auto or --plan, the flag overrides whatever mode the session was saved with. The --yolo flag deserves its own risk discussion, which is exactly what the Kimi Code YOLO mode guide is for.

Project instructions: AGENTS.md

Kimi Code follows the AGENTS.md convention. It reads a global file at ~/.kimi-code/AGENTS.md, a shared one at ~/.agents/AGENTS.md, and your project's AGENTS.md. There is no KIMI.md, and it does not read CLAUDE.md natively, though it ships an import skill that converts an existing Claude Code or Codex setup once, with your confirmation.

Skills are shared, not ported

Kimi Code reads skills natively from ~/.agents/skills/, the same shared folder other CLI agents use, plus its own ~/.kimi-code/skills/ and per-project skill folders. If you already maintain skills for Claude Code or Codex, Kimi Code picks them up without any porting. That makes the workflow in sharing skills between agents apply to Kimi out of the box.

MCP servers

MCP configuration is file-based. Kimi Code reads a global ~/.kimi-code/mcp.json, then your repository's .mcp.json at the git root (the same file Claude Code uses, so one file can serve both agents), then a per-project .kimi-code/mcp.json, with the more specific file winning. Tool names follow the same mcp__server__tool pattern as Claude Code. There is no --mcp-config flag, configuration lives in files only. For deeper automation there is also a full hooks system, configured in TOML inside ~/.kimi-code/config.toml and validated with kimi doctor.

Running Kimi Code inside CodeAgentSwarm

One Kimi Code session is one process working on one task. The moment you want a second task moving at the same time, you are into multiple terminals, and that is where CodeAgentSwarm comes in. It is a desktop app for macOS and Windows that runs several AI CLI terminals in one visual workspace, and Kimi Code is a first-class agent in it, alongside Claude Code, Codex CLI, Antigravity CLI and opencode.

You pick the agent per terminal, so you can run three Kimi Code sessions side by side, or mix Kimi with Claude Code on the same project and compare how each handles its task. On top of the terminals you get desktop notifications when an agent finishes or asks for input, searchable conversation history across every agent, per-terminal live diffs of what each session changed, a kanban board the agents update over MCP, and a quota indicator that reads Kimi's weekly and 5-hour windows so you see a wall coming before you hit it.

From here, the natural next steps are running multiple Kimi Code sessions for the mechanics, and the Kimi Code agent swarm guide for the full parallel workflow. If you would rather keep your existing harness and just use the model, you can also run Kimi K3 inside Claude Code.