How to Use Kimi Code: Complete Setup and Workflow Guide for the AI Terminal Coding Assistant

Kimi Code is a terminal-based AI coding assistant that you install via a single curl command, authenticate with /login, and launch with kimi to start interactive coding sessions with slash commands and sub-agents.

This guide covers the complete workflow for using Kimi Code based on its actual source architecture in the MoonshotAI/kimi-code repository. Kimi Code functions as a monorepo-based system with three core layers: the CLI/TUI interface in apps/kimi-code, the agent orchestration engine in packages/agent-core and packages/agent-core-v2, and the REST/WebSocket server in packages/kap-server.

Install Kimi Code

Kimi Code distributes as a standalone binary that requires no Node.js runtime, making installation immediate across platforms.

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

Verify Installation

kimi --version

The installer places the binary on your PATH. For development or programmatic access, you can also install via npm from the monorepo's published packages.

Authenticate and Configure

Before starting your first session, you must authenticate Kimi Code with either OAuth or a direct API key.

Launch and Login

cd /path/to/your-project
kimi

Once the TUI opens, execute:

/login

This prompts for Moonshot AI credentials or API key entry. Authentication state persists across sessions.

Configure MCP (Model Context Protocol)

Kimi Code stores MCP configuration in <cwd>/.kimi-code/mcp.json. Edit this directly or use:

/mcp-config

The packages/kap-server/AGENTS.md reference details how the server layer handles these protocol configurations for external tool integration.

Start a Coding Session

The core Kimi Code workflow begins when you invoke kimi from within a project directory. The CLI entry point at apps/kimi-code/src/index.ts bootstraps the TUI and initializes the agent engine.

Basic Session Flow

cd my-project
kimi

The interface presents a chat-style prompt where you type natural language requests. The input passes to the agent engine (packages/agent-core or packages/agent-core-v2 depending on feature flags), which determines tool selection and execution.

Architecture: How Your Commands Execute

When you submit a request, Kimi Code processes it through this pipeline:

Stage	Component	Source Location
Input capture	TUI renderer	apps/kimi-code
Intent parsing	Agent engine	packages/agent-core/README.md
Tool orchestration	DI × Scope engine	packages/agent-core-v2/AGENTS.md
Execution	Skills/sub-agents	plugins/official/*
Response rendering	TUI diff viewer	apps/kimi-code

The engine maintains scopes for context isolation and uses hooks for lifecycle events, as documented in the v2 architecture notes.

Core Slash Commands

Kimi Code exposes its functionality through slash commands parsed by the CLI and dispatched to the appropriate handler.

Task Management with /goal

For multi-step operations that persist across turns:

/goal Write a complete CRUD API for a Todo resource in Express

Monitor and control long-running goals:

/goal status   # View progress

/goal pause    # Suspend execution

/goal resume   # Continue from pause point

/goal cancel   # Terminate and cleanup

The goal system implements state machines in the agent engine, allowing resumption even across CLI restarts.

Configuration Commands

• /login – Re-authenticate or switch accounts
• /mcp-config – Edit Model Context Protocol settings
• /plugin – Plugin management namespace

Execution Commands

• /exec <command> – Run shell commands in sandboxed environment
• /coder – Explicitly invoke the code-writing sub-agent
• /explore – Trigger codebase analysis sub-agent

Extend Kimi Code with Plugins

Plugins add skills, data sources, and UI extensions. The official plugin registry lives in plugins/official/.

Install a Plugin

/plugin install kimi-webbridge

The system fetches from the marketplace, validates trust badges, and hot-loads the skill. The plugins/official/kimi-webbridge/SKILL.md demonstrates how skills integrate browser control capabilities.

Plugin Architecture

Plugins hook into:

• Skill definitions – Tool implementations the agent can invoke
• Lifecycle hooks – Pre/post execution callbacks
• Data providers – Custom context injection

Programmatic Usage with the Node SDK

For embedding Kimi Code capabilities in applications, the packages/node-sdk/README.md documents the public TypeScript SDK:

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

const client = new KimiClient({
  apiKey: process.env.KIMI_API_KEY
});

const session = await client.createSession({
  workspace: './my-project'
});

await session.send('Refactor the authentication module');

The SDK communicates with the same packages/kap-server REST/WebSocket endpoints that the CLI uses.

Key Source Files Reference

File	Purpose	Direct Link
Root README	Installation, quick-start, overview	README.md
Agent core	Core DI × Scope engine documentation	packages/agent-core/README.md
Agent core v2	v2 engine architecture and flags	packages/agent-core-v2/AGENTS.md
KAP server	REST/WebSocket API, debug RPC	packages/kap-server/AGENTS.md
CLI entry	TUI bootstrap and initialization	apps/kimi-code/src/index.ts
WebBridge skill	Browser automation example	plugins/official/kimi-webbridge/SKILL.md
Node SDK	Programmatic TypeScript client	packages/node-sdk/README.md
MiniDB	Embedded JSON store for search index	packages/minidb/README.md

Summary

• Install Kimi Code via single-line curl/PowerShell scripts—no Node.js dependency required
• Authenticate with /login using OAuth or API key before first use
• Launch sessions with kimi in project directories; the TUI provides chat-based interaction
• Control execution through slash commands: /goal for persistent tasks, /exec for shell commands, /plugin for extensions
• Understand architecture: CLI → Agent Engine (packages/agent-core-v2) → Skills/Plugins → Execution
• Extend functionality via plugin marketplace or custom skill development
• Integrate programmatically using the Node SDK against the KAP server REST/WebSocket API

Frequently Asked Questions

What makes Kimi Code different from other AI coding tools?

Kimi Code operates as a terminal-native application rather than an IDE plugin or web interface. Its three-layer architecture—thin TUI, heavy agent engine, and optional server—enables both interactive use and headless integration. The DI × Scope engine in packages/agent-core-v2 provides sophisticated context management through dependency injection and isolated scopes, supporting complex multi-file operations with state persistence.

Can I use Kimi Code without an internet connection?

Partial functionality works offline after initial setup, but core LLM inference requires connectivity to Moonshot AI's services. The local components—agent engine, skill execution, file operations, and shell command running—operate entirely on your machine. The packages/kap-server can be configured for local model inference if you deploy compatible endpoints.

How do I troubleshoot plugin installation failures?

First verify network connectivity to the marketplace endpoint. Run /plugin list to check registry reachability. If a specific plugin fails, examine <cwd>/.kimi-code/logs/ for download and validation errors. Plugin trust verification requires intact signature chains; disable strict validation only in development environments via MCP configuration. The plugins/official/ directory contains reference implementations for debugging custom plugins.

What security model applies to shell command execution?

Kimi Code uses sandboxed shell execution with configurable permission levels. The /exec command runs in isolated subprocesses with filesystem access limited to the workspace directory. The engine in packages/agent-core implements approval gates for destructive operations and maintains execution logs for audit. Review and modify sandbox policies in your .kimi-code/mcp.json configuration file.

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