How to Report a Bug in Kimi-CLI: A Complete Guide

Report bugs in Kimi-CLI by enabling debug mode with --debug, capturing the full log output, documenting your environment (Python, uv, and OS versions), and submitting a detailed issue via the GitHub bug report template at .github/ISSUE_TEMPLATE/bug_report.md.

Kimi-CLI is an extensible Python command-line interface that orchestrates large-language-model (LLM) agents through a layered architecture. When something goes wrong, providing maintainers with precise diagnostic information from the source code layers—ranging from the CLI entry point in src/kimi_cli/cli/__init__.py to the wire protocol in src/kimi_cli/wire/protocol.py—is essential for rapid resolution.

Before You Submit: Search Existing Issues

Before creating a new report, search the GitHub Issues tab for similar problems. If you find an existing issue that describes your bug, add your debug logs and environment details as a comment rather than opening a duplicate.

Capture Debug Logs with the --debug Flag

The --debug flag activates verbose logging across the runtime layers, including the Wire protocol (src/kimi_cli/wire/protocol.py) and approval subsystem (src/kimi_cli/soul/approval.py). These logs contain timestamps and internal message IDs that map directly to the code execution flow.

Run your command with debug mode enabled:

uv run kimi --debug <your-command> [options]

Capture the complete output to a file for easy uploading:

uv run kimi --debug <your-command> [options] 2>&1 | tee kimi-debug.log

The debug output will include:

• Wire messages from src/kimi_cli/wire/__init__.py
• Tool execution details from src/kimi_cli/soul/toolset.py
• Agent loop state transitions from src/kimi_cli/soul/kimisoul.py
• Configuration loading traces from src/kimi_cli/app.py

Document Your Environment

Include the following details in your report to help maintainers reproduce the environment:

• Operating System and version (e.g., Ubuntu 22.04, macOS 14.2)
• Python version: python --version
• uv version: uv --version
• Kimi-CLI version: kimi --version (or git rev-parse HEAD if running from source)

Prepare a Minimal Reproducible Example

Isolate the bug to the smallest possible command or configuration. If the issue involves custom agents, include the minimal YAML spec file that triggers the problem. Agent specifications are processed by src/kimi_cli/agentspec.py and loaded during the bootstrap phase in src/kimi_cli/app.py.

Example minimal agent spec to include in your issue:

# minimal-bug-repro.yaml

name: bug-repro
extends: default
tools:
  - import_path: kimi_cli.tools.shell.run_shell
  - import_path: kimi_cli.tools.file.read_file

Also include any relevant configuration from ~/.kimi/config.toml (redact API keys).

Submit via the GitHub Bug Report Template

The repository includes a structured template at .github/ISSUE_TEMPLATE/bug_report.md. When you click New issue → Bug report, the template pre-populates sections for:

• Title: A concise description of the failure
• Description: What you expected versus what actually happened
• Reproduction steps: The exact command line executed
• Debug logs: Paste the output captured from --debug mode
• Environment: Python version, uv version, OS, and Kimi-CLI version
• Additional context: Custom agent specs or configuration files

Fill out each section completely. Attach the kimi-debug.log file rather than pasting long logs directly into the text box if they exceed 50 lines.

Summary

• Search first to avoid duplicate issues
• Use --debug to capture detailed logs from the Wire and Soul layers
• Document your environment including Python, uv, and OS versions
• Provide minimal reproduction steps and custom agent specs if applicable
• Use the template at .github/ISSUE_TEMPLATE/bug_report.md for consistent formatting

Frequently Asked Questions

Where does Kimi-CLI store its debug logs?

Kimi-CLI outputs debug information to stderr when the --debug flag is passed. You must manually redirect this output to a file using shell redirection (e.g., 2>&1 | tee debug.log). There is no default log file location; the runtime streams logs directly from src/kimi_cli/cli/__init__.py through the wire protocol layer.

What information should I redact from debug logs?

Remove sensitive information such as API keys, access tokens, and file paths that may contain personal information. The debug output from src/kimi_cli/soul/approval.py may include file contents if the bug involves file operations—review the log carefully before uploading to a public issue.

Why does the maintainer need my uv version?

Kimi-CLI uses uv as its package manager and runner. The uv version affects how dependencies are resolved and how the virtual environment is constructed, which can impact behavior in src/kimi_cli/app.py during the bootstrap phase. Including this information ensures maintainers can recreate your exact execution environment.

Can I report bugs for custom agent specifications?

Yes, but clearly indicate that the bug involves a custom agent spec (YAML file). Include the minimal spec that reproduces the issue, as the bug may reside in the inheritance resolution logic within src/kimi_cli/agentspec.py or the tool injection system in src/kimi_cli/soul/toolset.py. If the bug occurs only with specific extend values or custom tool imports, include those details in your reproduction steps.

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