Skip to content

kimi-tools

Generated from plugins/kimi-tools/README.md.

Package documentation: browse guides and development docs.

Kimi CLI-compatible plugin bundle. It provides manual conversation compaction and file, search, web, media, and shell tools with model-facing behavior based on MoonshotAI's kimi-cli.

The web-search tool exposes its ordinary web_search_enabled checkbox as a compact composer toggle. The control uses the same session override as full settings and remains visible but disabled when no configured search backend is available.

Manual conversation compaction

When enabled for an agent, KimiCompactionFeature exposes:

  • compact_conversation, which compacts the full conversation or an explicit Python-style start:end range;
  • compact_up_to_here, a message action that compacts the prefix ending at the selected message.

Full-conversation compaction preserves the last two user/assistant messages by default. It sends the earlier context to a tool-free compaction request using the Kimi prompt and injects the result as one user message beginning with:

<system>Previous context has been compacted. Here is the compaction output:</system>

Enable the feature in the agent configuration:

{
  "compaction": {
    "enabled": true,
    "type": "kimi",
    "max_preserved_messages": 2,
    "compaction_model": null,
    "prompt": null,
    "settings_overrides": {}
  }
}
  • max_preserved_messages defaults to 2. A value less than or equal to 0 makes an unbounded/full compaction request a no-op, matching kimi-cli.
  • compaction_model selects a model used only for compaction. The session settings UI can override it per session.
  • prompt replaces the default Kimi compaction prompt.
  • settings_overrides adds request settings, but cannot re-enable tools for the compaction request.

The prompt asks for Kimi's structured XML-style summary sections. If the model returns other non-empty text, the plugin retains it instead of rejecting an otherwise usable compaction.

Exposed Tools

ReadFile

Read text content from a file with line-numbered output (cat -n format).

  • Parameters: path (required), line_offset (default 1), n_lines (default 1000)
  • Limits: 1000 lines, 2000 chars/line, 100KB total output
  • Output: 6-digit right-aligned line numbers with tab separator
  • Truncation: Per-line truncation with "..." marker; Kimi-style truncation messages

ReadMediaFile

Read image media content from a local file and return it in model-visible form.

  • Parameters: path (required)
  • Capabilities: Exposed when kimi_read_media_capabilities includes image_in or video_in
  • Image support: PNG, JPEG, GIF, and WebP are returned as data URLs plus structured image output
  • Video support: Detected and capability-gated, but model-visible video output is currently deferred
  • Limits: 100MB by default via kimi_read_media_max_bytes
  • Output: Kimi-style <image path="...">...</image> fallback text, multipartContent for image-capable chat providers, and structured image output for providers that support it

FetchURL

Fetch a web page from a URL and extract main text content from it.

  • Parameters: url (required)
  • Primary path: Moonshot fetch service (when configured)
  • Fallback path: Local HTTP fetch + trafilatura extraction
  • No LLM summarization: Returns raw extracted text (unlike Gemini and Qwen)
  • Content types:
  • text/plain and text/markdown: passthrough (no extraction)
  • HTML: trafilatura extraction with Kimi-specific options
  • Limits: 50000 characters max
  • Extraction options: include_comments=True, include_tables=True, include_formatting=False, with_metadata=True

Moonshot Service Configuration

The Moonshot fetch service is opt-in. By default, FetchURL uses local HTTP fetch. To enable the service:

{
  "moonshot_enabled": true,
  "moonshot_api_key": "${MOONSHOT_API_KEY}"
}

Required when enabled: - moonshot_enabled: Set to true to enable the service - moonshot_api_key: API key (can use ${ENV_VAR} placeholder)

Optional: - moonshot_base_url: Service URL (default: https://api.kimi.com/coding/v1/fetch) - moonshot_custom_headers: Additional headers for requests

When enabled and configured, FetchURL will attempt the Moonshot service first, falling back to local fetch on failure.

Shell

Execute shell commands with clean environment support.

  • Parameters: command (required), timeout (default 60, max 300)
  • Timeout: In seconds; default 60s, max 300s
  • Clean environment: Removes PyInstaller/frozen-executable variables when running as frozen
  • Output format: Raw output + success/failure message
  • Truncation: Per-line truncation with "[...truncated]" marker, capped to 2000 chars/line and 50000 chars total

WriteFile

Write content to a file with overwrite or append mode.

  • Parameters: path (required), content (required), mode (default "overwrite")
  • Modes: "overwrite" replaces entire file; "append" adds to end

StrReplaceFile

Replace specific strings within a file. Supports single or multiple edits per call.

  • Parameters: path (required), edit (required — single Edit or list of Edit objects)
  • Edit struct: {old: str, new: str, replace_all: bool}
  • Multi-edit: Applies edits sequentially to file content

Glob

Find files and directories using glob patterns.

  • Parameters: pattern (required), directory (optional), include_dirs (default true)
  • Safety: Rejects patterns starting with ** with directory listing
  • Limits: 1000 matches maximum; alphabetical sort order

Grep

Search for patterns in file contents using regular expressions.

  • Parameters: pattern (required), path (default "."), glob, output_mode, -B, -A, -C, -n, -i, type, head_limit, multiline
  • Output modes: content, files_with_matches, count_matches
  • Backend: ripgrep (system rg binary) with Python fallback

Kimi-Specific Behavior Notes

  1. PascalCase tool names: ReadFile, ReadMediaFile, WriteFile, StrReplaceFile, Glob, Grep, FetchURL, Shell
  2. Line-numbered output: ReadFile returns cat -n style line numbers
  3. Append mode: WriteFile supports mode: "append" for appending content
  4. Multi-edit: StrReplaceFile accepts single Edit or list of Edit structs
  5. **-pattern blocking: Glob rejects patterns starting with **
  6. Multi-mode grep: Three output modes with ripgrep-style flags
  7. Different content limits: 1000 lines, 2000 chars/line, 100KB total
  8. Clean environment: Shell removes PyInstaller variables when running as frozen
  9. FetchURL no summarization: Returns raw extracted text without LLM summarization
  10. Trafilatura with metadata: FetchURL uses with_metadata=True for richer extraction

Configuration

{
  "working_directory": "/path/to/project",
  "allowed_paths": ["/path/to/project"],
  "project_temp_dir": "/path/to/project/.temp",
  "kimi_read_media_capabilities": ["image_in"],
  "kimi_read_media_max_bytes": 104857600,
  "shell_timeout_seconds": 60,
  "shell_max_timeout_seconds": 300,
  "shell_clean_env": true,
  "web_fetch_timeout_seconds": 10,
  "web_fetch_max_chars": 50000,
  "moonshot_enabled": false,
  "moonshot_api_key": "${MOONSHOT_API_KEY}",
  "compaction": {
    "enabled": true,
    "type": "kimi"
  }
}

Config keys:

File tools: - working_directory: Base for relative paths - allowed_paths: Allowed directories for file access - project_temp_dir: Default: <working_directory>/.temp - kimi_read_media_capabilities: Media capabilities for exposing ReadMediaFile; defaults to ["image_in"]. Use [] to hide the tool. - kimi_read_media_max_bytes: Maximum file size for ReadMediaFile; defaults to 104857600 bytes.

Shell tool: - shell_timeout_seconds: Default timeout for shell commands (default: 60) - shell_max_timeout_seconds: Maximum allowed timeout (default: 300) - shell_clean_env: Use clean environment for subprocess (default: true)

FetchURL tool: - web_fetch_timeout_seconds: HTTP fetch timeout in seconds (default: 10) - web_fetch_max_chars: Maximum content length in characters (default: 50000) - moonshot_enabled: Enable Moonshot fetch service (default: false, opt-in) - moonshot_api_key: API key for Moonshot service, can use ${ENV_VAR} placeholder - moonshot_base_url: Moonshot service URL (default: https://api.kimi.com/coding/v1/fetch) - moonshot_custom_headers: Additional headers for service requests (optional)

Manual compaction:

  • compaction.enabled: Enable the compaction actions.
  • compaction.type: Must be "kimi" for this feature.
  • compaction.max_preserved_messages: Recent user/assistant messages kept verbatim during full-conversation compaction; defaults to 2.
  • compaction.compaction_model: Optional model dedicated to compaction.
  • compaction.prompt: Optional replacement compaction prompt.
  • compaction.settings_overrides: Optional request settings; tools remain disabled regardless of this mapping.

Dependencies

  • tool-compat-shared (shared filesystem/search helpers)
  • web-fetch-shared (shared HTTP fetch and trafilatura extraction)
  • System rg (ripgrep) binary recommended for Grep tool performance

Development

pip install -e ".[dev]"
pytest tests -q

License

Copyright 2026 Dynamic Programming Solutions Kft.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.