How to Report a Bug in Kimi Code: A Step-by-Step Guide

Reporting a bug in Kimi Code requires verifying the issue, collecting environment details and debug logs, and submitting a structured report through the GitHub issue template.

The Kimi Code repository from MoonshotAI maintains a straightforward workflow to ensure maintainers can efficiently reproduce and fix issues. Understanding how to report a bug in kimi-code correctly saves time and increases the likelihood of a rapid resolution. This guide walks through the exact process defined in the repository's governance files, from initial verification to final submission.

Verify and Gather Context

Before opening an issue, confirm that the unexpected behavior is an actual bug rather than a configuration error or documented limitation. Once verified, collect the specific details maintainers need to investigate.

Confirm the Issue is a Bug

Check the official guides and existing issues to ensure the behavior is not a known limitation or user error. The maintainers emphasize that new bug-related changes should be preceded by an issue, and pull requests without linked issues may be closed without review according to CONTRIBUTING.md.

Collect Environment Details

Document the following information before filing:

• Kimi Code version: Run kimi --version to capture the exact release.
• Operating system: Note the OS and architecture (e.g., macOS 14.2 arm64, Ubuntu 22.04 x64).
• Package scope: If the bug appears in a specific package (e.g., @moonshot-ai/agent-core), include the package name.
• Reproduction steps: List the minimal commands, CLI flags, or ACP commands that trigger the issue.

Capture Debug Logs

The CLI provides two methods to enable detailed debug logging as implemented in packages/pi-tui/src/tui.ts:

1. Environment variable: Set KIMI_DEBUG=1 before running commands.
2. TUI shortcut: Press Shift + Ctrl + D while in the TUI interface.

Debug logs are written to ~/.pi/agent/pi-debug.log by default. Include relevant excerpts in your report, redacting any sensitive information.

# Enable debug logging and reproduce the bug

KIMI_DEBUG=1 kimi run /my-task

# Retrieve the generated debug log

cat ~/.pi/agent/pi-debug.log

Submit Your Bug Report

Once you have gathered the necessary context, use the repository's structured template to ensure consistency.

Use the GitHub Issue Template

Navigate to the repository's Issues page and click New issue. Select the Bug report template, which is defined in .github/ISSUE_TEMPLATE/bug_report.md. Fill in all sections including:

• Version and OS
• Steps to reproduce
• Expected behavior versus Actual behavior
• Relevant log output

You can also use the GitHub CLI to create the issue with the template pre-selected:

gh issue create \
  --title "Bug: CLI crashes on Windows when using --work-dir" \
  --label bug \
  --template bug_report.md \
  --assignee "@moonshot-ai"

Handle Security Bugs Privately

If the bug involves security concerns—such as credential exposure or denial-of-service vectors—do not open a public issue. Instead, follow the instructions in SECURITY.md to report the vulnerability privately to the maintainers.

Contributing Bug Fixes

If you plan to submit a code fix, reference the issue number in your pull request. The contribution guidelines in CONTRIBUTING.md explicitly require that bug fixes be linked to an existing issue to streamline the review process. The README.md file provides additional entry points and links to the issue tracker for navigation.

Summary

• Verify first: Confirm the issue is a bug and not a configuration problem before filing.
• Gather details: Document the version (kimi --version), OS, reproduction steps, and relevant package names.
• Enable debugging: Use KIMI_DEBUG=1 or Shift + Ctrl + D to capture logs from ~/.pi/agent/pi-debug.log as implemented in packages/pi-tui/src/tui.ts.
• Use templates: Submit reports via the .github/ISSUE_TEMPLATE/bug_report.md template on GitHub.
• Security matters: Report vulnerabilities privately through SECURITY.md, never via public issues.
• Link issues: When contributing fixes, ensure your PR references the bug report to comply with CONTRIBUTING.md requirements.

Frequently Asked Questions

How do I enable debug logging in Kimi Code?

You can enable debug logging by setting the environment variable KIMI_DEBUG=1 before running any command, or by pressing Shift + Ctrl + D while using the TUI interface. The logs are saved to ~/.pi/agent/pi-debug.log and provide detailed trace information necessary for debugging complex issues.

Where is the bug report template located?

The bug report template is stored at .github/ISSUE_TEMPLATE/bug_report.md in the MoonshotAI/kimi-code repository. When you click New issue on GitHub, selecting the Bug report option automatically loads this template, ensuring you provide all required fields like version, OS, and reproduction steps.

Can I submit a bug fix without opening an issue first?

No, the maintainers require that all bug-related changes be preceded by an issue. According to CONTRIBUTING.md, pull requests without a linked issue may be closed without review. Opening an issue first allows the team to triage the problem and discuss the proposed solution before you invest time in coding.

What should I do if I find a security vulnerability?

Do not open a public GitHub issue for security bugs. Instead, consult the SECURITY.md file in the repository root for instructions on how to report vulnerabilities privately. This policy protects users from exposure while the maintainers develop and deploy a patch.

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