How to Use Kimi K3 in Aider and Claude Code: Setup Guide

Kimi K3 scores 88.3% on Terminal-Bench 2.1 and costs $3/$15 per million tokens (with cache hits dropping input to $0.30/M). That makes it one of the best value propositions for agentic coding tools like Aider and Claude Code.

This guide walks you through setting up K3 in both tools via OpenRouter.

Prerequisites

Before starting, you need:

1. An OpenRouter account with credits loaded
2. An OpenRouter API key (generate from dashboard)
3. Aider installed (pip install aider-chat) or Claude Code installed
4. A terminal with your development environment ready

Setting Up Kimi K3 in Aider

Method 1: Command Line Flag

The simplest approach for a one-off session:

export OPENROUTER_API_KEY="your-key-here"

aider --model openrouter/moonshotai/kimi-k3

This launches Aider with K3 as the main model. Aider handles the OpenRouter routing automatically when you prefix the model name with openrouter/.

Method 2: Environment Variables (Persistent)

Add to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):

export OPENROUTER_API_KEY="your-openrouter-api-key"
export AIDER_MODEL="openrouter/moonshotai/kimi-k3"

Now running aider without arguments defaults to K3.

Method 3: Aider Configuration File

Create or edit ~/.aider.conf.yml:

model: openrouter/moonshotai/kimi-k3

Or for project-specific configuration, create .aider.conf.yml in your project root:

model: openrouter/moonshotai/kimi-k3
auto-commits: true

Method 4: Using K3 as Architect + Cheaper Editor

Aider supports architect mode where one model plans and another executes. Use K3 as the architect and a cheaper model as the editor:

aider --architect --model openrouter/moonshotai/kimi-k3 --editor-model openrouter/deepseek/deepseek-v4-pro

This leverages K3’s superior reasoning for planning while using a cheaper model for the actual file edits. K3’s 88.3% Terminal-Bench score makes it excellent at understanding what needs to change, and the editor model applies those changes.

Optimizing Aider for K3’s Cache

K3 achieves 90%+ cache hit rates with consistent prefixes. Aider naturally sends the same context repeatedly (system prompt + file contents), which aligns well with K3’s caching.

To maximize cache benefits:

1. Keep files loaded consistently. Do not add and remove files from context frequently. Load what you need at the start and keep it.
2. Use /add to load files early. More context upfront means more cacheable prefix in subsequent requests.
3. Avoid switching models mid-session. Each model switch resets the cache context.

Verifying K3 is Working in Aider

After launching, run a quick test:

> /model
Currently using: openrouter/moonshotai/kimi-k3

> Write a hello world in Python

# K3 should respond with clean code and offer to create the file

If you see the model name confirmed and get high-quality responses, the setup is working.

Setting Up Kimi K3 in Claude Code

Claude Code is designed for Anthropic models but can be configured to use other models through OpenRouter.

Method 1: OpenRouter Provider Configuration

Set the environment variables to point Claude Code at OpenRouter:

export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="your-openrouter-api-key"
export ANTHROPIC_MODEL="moonshotai/kimi-k3"

Then launch Claude Code normally:

claude

Method 2: Per-Session Override

For trying K3 without changing your default configuration:

ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1" \
ANTHROPIC_API_KEY="your-openrouter-key" \
ANTHROPIC_MODEL="moonshotai/kimi-k3" \
claude

Method 3: Configuration File

Check Claude Code’s configuration documentation for the current config file location and format. Add the OpenRouter base URL and model specification to your config.

Important Notes for Claude Code

• Claude Code’s tool use and computer use features are designed for Anthropic models. K3 supports function calling, but some advanced Claude Code features may not work perfectly.
• For the best Claude Code experience with Anthropic models, see our Claude Code guide.
• If you hit compatibility issues, Aider tends to be more flexible with non-Anthropic models.

Hybrid Setup: K3 + Another Model

Many developers use different models for different tasks. Here are practical hybrid setups:

K3 for Coding + Opus for Reviews

Use K3 for primary development (it is cheaper and scores higher on Terminal-Bench) and switch to Opus 4.8 for code review or safety-critical sections:

# Primary coding
aider --model openrouter/moonshotai/kimi-k3

# Switch for review (in a different terminal or session)
aider --model openrouter/anthropic/claude-opus-4.8

K3 as Primary + Sonnet 5 for Quick Tasks

For quick edits where K3’s power (and cost) is overkill, keep a Sonnet 5 session handy:

# Complex work
alias aider-k3="aider --model openrouter/moonshotai/kimi-k3"

# Quick tasks
alias aider-sonnet="aider --model openrouter/anthropic/claude-sonnet-5"

K3 Architect + Grok Editor

Grok 4.5 at $2/$6 is a solid budget editor model:

aider --architect --model openrouter/moonshotai/kimi-k3 --editor-model openrouter/xai/grok-4.5

Performance Tips

1. Load Context Strategically

K3’s 1M token context window means you can load substantial portions of a codebase. But more context means more cost on the first request (before cache kicks in). Start with the most relevant files:

> /add src/auth/login.py src/auth/session.py src/models/user.py

2. Use Repo Map

Aider’s repo map feature gives K3 an overview of your project structure without loading every file. This helps K3 understand the codebase architecture while keeping token usage reasonable:

aider --model openrouter/moonshotai/kimi-k3 --map-tokens 2048

3. Enable Auto-Commits

With K3’s 88.3% Terminal-Bench score, its changes are correct more often than not. Enable auto-commits to maintain a clean git history of model changes:

aider --model openrouter/moonshotai/kimi-k3 --auto-commits

You can always git revert if something goes wrong.

4. Watch Token Usage

Monitor costs during development:

> /tokens

K3’s cache means subsequent requests in the same session are cheaper. The first request in a session costs full price; subsequent ones benefit from prefix caching.

Troubleshooting

”Model not found” Error

Verify the model ID is exactly moonshotai/kimi-k3 (when using OpenRouter prefix in Aider: openrouter/moonshotai/kimi-k3). Check OpenRouter’s model page for the current model ID if this does not work.

Slow Responses

K3 uses a Mixture-of-Experts architecture with 2.8T total parameters. First-token latency may be slightly higher than dense models. For streaming output, this usually matters only for the first few tokens.

Rate Limiting

If you hit rate limits on OpenRouter:

1. Check your account tier and limits on the OpenRouter dashboard
2. Add a short delay between rapid-fire requests
3. Consider upgrading your OpenRouter tier for higher limits

Context Length Exceeded

K3 supports 1M tokens, but if you exceed this:

1. Remove less-relevant files from context: /drop filename.py
2. Reduce map tokens: --map-tokens 1024
3. Start a fresh session if context is filled with old conversation history

Cost Expectations

Here is what to expect cost-wise for a typical Aider session with K3:

Session Type	Approximate Cost
Quick fix (5 minutes, 2-3 exchanges)	$0.10 - $0.30
Feature implementation (30 min, 10 exchanges)	$0.50 - $2.00
Heavy refactoring (2 hours, 30+ exchanges)	$3.00 - $8.00
Full day of development	$10.00 - $25.00

Cache hits reduce these costs by 30-50% for input tokens after the first exchange. The output cost ($15/M) dominates for longer responses.

Compare this to Sol at $5/$30 where the same workloads would cost roughly double.

FAQ

Does K3 work well with Aider’s diff format?

Yes. K3 handles Aider’s unified diff and whole-file edit formats well. Its 88.3% Terminal-Bench score indicates strong capability at structured output tasks, which is exactly what Aider’s diff format requires.

Is K3 better than Opus 4.8 in Aider?

For most coding tasks, K3 benchmarks higher (88.3% Terminal-Bench, 67.5% DeepSWE) and costs less ($3/$15 vs $5/$25). The experience in Aider should reflect these benchmarks. See our K3 vs Opus comparison for the full analysis.

Can I use K3 for both architect and editor roles in Aider?

You can, but it is expensive since both roles use the $15/M output pricing. Using K3 as architect and a cheaper model (Grok 4.5 at $2/$6, or Sonnet 5 at $2/$10) as editor is more cost-effective.

How does K3 compare to Claude models in Claude Code?

K3 outperforms Opus 4.8 on coding benchmarks. However, Claude Code is built specifically for Anthropic models, so some features may work better with Claude. If you want the best Claude Code experience, stick with Anthropic models. If you want the best raw coding performance and are comfortable with potential quirks, K3 through OpenRouter is worth trying.

What is the best model combination for cost vs performance?

K3 as architect ($3/$15) with Grok 4.5 as editor ($2/$6) gives you frontier-level planning at budget execution costs. For teams tracking expenses, this combination provides excellent results per dollar.