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

> Learn how to use Kimi Code, an AI terminal coding assistant. Get the complete setup and workflow guide for efficient AI-powered coding sessions.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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](https://github.com/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

```bash
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

```

### Windows (PowerShell)

```powershell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

```

### Verify Installation

```bash
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

```bash
cd /path/to/your-project
kimi

```

Once the TUI opens, execute:

```text
/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:

```text
/mcp-config

```

The [packages/kap-server/AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/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](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/index.ts) bootstraps the TUI and initializes the agent engine.

### Basic Session Flow

```bash
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](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/README.md) |
| Tool orchestration | DI × Scope engine | [packages/agent-core-v2/AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/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:

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

```

Monitor and control long-running goals:

```text
/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

```text
/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](https://github.com/MoonshotAI/kimi-code/blob/main/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](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/README.md) documents the public TypeScript SDK:

```typescript
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](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/AGENTS.md) REST/WebSocket endpoints that the CLI uses.

## Key Source Files Reference

| File | Purpose | Direct Link |
|------|---------|-------------|
| Root README | Installation, quick-start, overview | [README.md](https://github.com/MoonshotAI/kimi-code/blob/main/README.md) |
| Agent core | Core DI × Scope engine documentation | [packages/agent-core/README.md](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/README.md) |
| Agent core v2 | v2 engine architecture and flags | [packages/agent-core-v2/AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/AGENTS.md) |
| KAP server | REST/WebSocket API, debug RPC | [packages/kap-server/AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/AGENTS.md) |
| CLI entry | TUI bootstrap and initialization | [apps/kimi-code/src/index.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/index.ts) |
| WebBridge skill | Browser automation example | [plugins/official/kimi-webbridge/SKILL.md](https://github.com/MoonshotAI/kimi-code/blob/main/plugins/official/kimi-webbridge/SKILL.md) |
| Node SDK | Programmatic TypeScript client | [packages/node-sdk/README.md](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/README.md) |
| MiniDB | Embedded JSON store for search index | [packages/minidb/README.md](https://github.com/MoonshotAI/kimi-code/blob/main/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](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/AGENTS.md) 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/](https://github.com/MoonshotAI/kimi-code/blob/main/plugins/official/kimi-webbridge/SKILL.md) 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`](https://github.com/MoonshotAI/kimi-code/blob/main/.kimi-code/mcp.json) configuration file.