Kimi Code harness extension for Pi. Pi v0.82.0 ships a built-in
kimi-codingprovider that handles the LLM layer — K3, adaptive thinking, and a generated model catalog — plus native OAuth sign-in via/login. This extension brings the rest of the Kimi Code surface into Pi: shared login state with the officialkimi-codeCLI, Kimi Files API uploads, and Kimi-native tools such asmoonshot_search,moonshot_fetch, andkimi_datasource.
Pi's built-in kimi-coding provider handles the LLM. This extension covers the rest: shared login state with the official CLI, file uploads through Kimi's Files API, and Kimi-native tools. It also keeps a legacy provider registration so existing model sessions still load. New users should use Pi's built-in model provider.
Live model catalog (legacy). For backward compatibility, the extension still reads Kimi's live
/v1/modelscatalog when it has credentials. New Pi users should rely on the built-in provider's generated catalog instead.
Pi is a small harness you adapt to your own workflow. Kimi Code is Moonshot's official coding agent. Pi now ships a built-in kimi-coding provider that covers the LLM, including OAuth login. This extension is for the parts of Kimi Code that Pi's built-in provider does not cover: the account session, file uploads, and Kimi's own tools/datasource APIs.
Use the built-in provider if you only want to chat with Kimi models. Install this extension when you also want the full Kimi Code surface inside Pi:
- Share a session with the official
kimi-codeCLI. Reuse an existingkimi-codelogin, or sync Pi's OAuth login back tokimi-codeso both CLIs stay authenticated. - Send files the Kimi way. Large inline images go through Kimi's Files API and become
ms://references instead of huge base64 payloads. - Use Kimi-native tools.
moonshot_search,moonshot_fetch, andkimi_datasourceare opt-in tools that call Moonshot's server-side services. - Keep Pi's tools working. Moonshot's API rejects tool schemas over 15 KB — a limit that Pi's extension ecosystem regularly hits (#16, #21). This extension automatically deduplicates schemas with
$ref/$defsbefore sending, so subagents and other extensions don't break. - Embed in your own build. The
KimiCode()factory lets you ship Kimi Code support inside a custom Pi agent with programmatic config overrides — no file-based extension path needed.
- Credential reuse with
kimi-code. Reads~/.kimi-code/credentials/kimi-code.jsonand syncs refreshed OAuth tokens back to it. - Kimi account login in Pi.
/login kimi-codingstores credentials in~/.pi/agent/auth.json; tokens refresh automatically. KIMI_API_KEYfallback. For CI or key-based access.- Kimi Files API uploads. Uploads large inline images and references them as
ms://instead of inline base64. - Optional Kimi-native tools.
moonshot_search,moonshot_fetch, andkimi_datasourcevia/kimi-settings. - Tool schema dedup. Collapses repeated
$ref/$defsstructures to stay under Moonshot's 15 KB per-tool limit. - Legacy provider registration. Keeps existing model sessions loading; new users should use Pi's built-in provider.
- Programmatic
KimiCode()factory. Embed Kimi Code in a custom Pi build with config overrides. - No build step. Pi loads the TypeScript extension directly.
From npm:
pi install npm:pi-provider-kimi-codeOr load a local checkout without installing:
pi -e /path/to/pi-provider-kimi-codeIf you prefer not to use npm, download the tarball from the latest release, extract it, and install from the local path:
curl -L https://github.com/Leechael/pi-provider-kimi-code/releases/latest/download/pi-provider-kimi-code.tar.gz | tar -xz -C /tmp
pi install /tmp/pi-provider-kimi-codeUse KimiCode() to embed Kimi Code as a provider inside a custom Pi build:
import { main } from "@earendil-works/pi-coding-agent";
import { KimiCode } from "pi-provider-kimi-code";
main(process.argv.slice(2), {
extensionFactories: [KimiCode({ protocol: "anthropic" })],
});KimiCode() with no arguments behaves identically to the file-based extension. Pass a KimiCodeConfigPatch to override defaults (protocol, upload threshold, tools, model parameters). See docs/programmatic-usage.md for the full API.
Pi's built-in kimi-coding provider already supports OAuth login via /login. This extension handles the credential layer around that login:
- Syncs refreshed tokens back to
kimi-code. Pi stores credentials at~/.pi/agent/auth.json; this extension keeps the official CLI's credential file (~/.kimi-code/credentials/kimi-code.json) up to date so both stay authenticated. - Reuses existing
kimi-codesessions. If you already use the official CLI, the extension reads its session directly. SetKIMI_CODE_HOMEif its home directory lives somewhere else. - Supports the legacy
~/.kimipath. Read-only. SetKIMI_SHARE_DIRto override it. KIMI_API_KEYfallback. For CI or key-based access:
KIMI_API_KEY=sk-... piNew users: Use Pi's built-in
kimi-codingprovider for model discovery, reasoning controls, and OAuth login. This extension keeps its own model registration only for backward compatibility with existing sessions.
When this extension does register models, the official catalog determines what it publishes. The following IDs are the fallback set when catalog discovery is unavailable:
| Pi model ID | Default name | Availability and context |
|---|---|---|
kimi-coding/kimi-for-coding |
Kimi K2.7 Code | Official catalog |
kimi-coding/kimi-for-coding-highspeed |
Kimi K2.7 Code HighSpeed | Official catalog |
kimi-coding/k3 |
Kimi K3 | Official catalog |
Kimi's official catalog at https://api.kimi.com/coding/v1/models is authoritative for model availability and context windows. When discovery is unavailable, the extension uses the fallback models and defaults below.
Fallback values:
- Context window:
256ktokens - Max output:
32ktokens - Input: text and image
- Reasoning: enabled
The provider maps Pi's reasoning levels to Kimi's top-level thinking parameter. It sends thinking.effort only when the official catalog advertises the mapped value. The mapping refreshes automatically on credential refresh. Opening /kimi-settings also re-discovers the latest model metadata.
Switching models or thinking effort invalidates Kimi's existing context cache. Start a new session when switching to avoid re-prefilling a long conversation and consuming extra quota.
Kimi Code has server-side capabilities that this extension exposes as opt-in tools. All tools are off by default. Enable them individually through /kimi-settings or JSON config.
Inside Pi, run:
/kimi-settings
That command shows the current server-side model name (e.g. "K2.7 Code High Speed"), your Kimi quota and Extra Usage balance, and lets you edit the home or project config. Changes apply to the active session tool set.
Configurable settings include protocol mode, upload threshold, and per-tool enable/collapse.
Config files are JSON:
- Home:
~/.pi/providers/kimi-coding/config.json - Project override:
<cwd>/.pi/providers/kimi-coding/config.json
Project config overrides home config with a deep merge. Missing files or missing keys mean all tools stay off.
| Tool | Description |
|---|---|
moonshot_search |
Web search through Kimi's Moonshot service |
moonshot_fetch |
Web page fetch through Kimi's Moonshot service |
kimi_datasource |
Unified Kimi datasource tool |
{
"protocol": "openai",
"uploads": { "thresholdBytes": 1048576 },
"tools": {
"moonshot_search": { "enabled": true, "default_collapsed": true },
"moonshot_fetch": { "enabled": true, "default_collapsed": true },
"kimi_datasource": { "enabled": true, "default_collapsed": true }
}
}kimi_datasource calls Kimi's /tools endpoint. It accepts data_source_name plus optional api_name and params:
- Without
api_name: returns the datasource description (available APIs). - With
api_nameandparams: calls the specified API.
Supported datasource names:
| Datasource | Description |
|---|---|
stock_finance_data |
Chinese stock and financial data |
yahoo_finance |
Yahoo Finance market data |
world_bank_open_data |
World Bank open statistics |
tianyancha |
Chinese enterprise and corporate data |
arxiv |
Academic paper search and metadata |
scholar |
Academic literature search |
yuandian_law |
Chinese legal database and case law |
All tools require /login kimi-coding OAuth credentials. KIMI_API_KEY is not used for these tools. Your account also needs access to Moonshot's server-side services; if not, the upstream service can return subscription or whitelist errors.
default_collapsed controls only the TUI preview. The full tool result still goes to the model; set it to false if you want previews expanded by default.
If you already use another search or fetch tool, pick one path for a session. Overlapping tools can make the model choose the wrong one.
Most users do not need environment variables. Two are worth knowing:
KIMI_API_KEY— static API key for CI or key-based access.KIMI_CODE_PROTOCOL—openaiby default; set toanthropicfor Anthropic-compatible requests.
Tools, protocol, and upload threshold are all configurable through /kimi-settings or JSON config files.
The full env list, including base URL overrides, kimi-code path overrides, upload tuning, debug logs, and model metadata overrides, lives in docs/ENV.md.
kimi-code is Moonshot's official terminal agent. Pi is the harness you adapt to your own workflow. Pi's built-in kimi-coding provider handles the LLM; this extension adds the rest of the Kimi Code surface to Pi.
Kimi's cache is content-based and keyed purely by prompt prefix. prompt_cache_key, Anthropic cache_control markers, and device-id headers are ignored. Cache benefits accrue within a session, not across cold starts. See docs/caching.md for measured behavior.
Kimi's coding endpoint speaks both Anthropic and OpenAI dialects. This extension defaults to OpenAI-compatible mode (/coding/v1/chat/completions) because it uses a dedicated role: "tool" message, which keeps tool results separate from user messages in multi-turn loops. Anthropic mode (/coding/v1/messages) is available if your setup depends on Anthropic-style semantics. See issue #5 for details.
No. This is an independent extension. The login flow is derived from the public implementation in the open-source Kimi Code repository.
Pi uses Node's fetch / undici stack, which handles http_proxy / https_proxy / all_proxy differently from curl. Check the proxy variables in the Pi process's environment. scripts/test_e2e.sh prints the effective proxy settings for debugging.
The login flow always prints a verification URL. Copy it into a browser manually if your terminal or OS blocks auto-open.
Your Moonshot account needs an active Kimi Code Plan. If the same account works in kimi-code, re-run /login kimi-coding to refresh credentials.
Run /kimi-settings and check whether the tool is enabled in the home or project config. All tools require OAuth login; KIMI_API_KEY is not enough. Subscription or whitelist errors come from the upstream Moonshot service.
This extension uploads images over KIMI_CODE_UPLOAD_THRESHOLD_BYTES (default 1 MB) to Kimi's Files API and references them as ms://. Set KIMI_CODE_DEBUG=1 to see upload decisions in the provider logs.
Cache benefits accrue within a single session. If cache_read_input_tokens (Anthropic) or cached_tokens (OpenAI) stays at 0, something in the prompt is varying between turns — a changed system prompt, tool set, ms:// reference, or timestamp. See docs/caching.md for the full list of invalidation causes and measurement scripts.
In OpenAI mode this extension maps developer to system because Kimi's Coding endpoint does not recognize developer. Use Anthropic mode if your toolchain expects developer to round-trip.
- Pi: earendil-works/pi
- Environment variables: docs/ENV.md
- Programmatic usage: docs/programmatic-usage.md
- Testing guide: docs/TESTING.md
- Cache behavior: docs/caching.md
- Architecture notes: docs/architecture.md
MIT