# How to Report a Bug in Kimi Code: A Step-by-Step Guide > Learn how to report a bug in Kimi Code with our step-by-step guide. Follow these instructions to provide necessary details and submit effective bug reports for the MoonshotAI/kimi-code repository. - Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code) - Tags: how-to-guide - Published: 2026-07-24 --- **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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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. ```bash # 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`](https://github.com/MoonshotAI/kimi-code/blob/main/.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: ```bash 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) explicitly require that bug fixes be linked to an existing issue to streamline the review process. The [`README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/tui.ts). - **Use templates**: Submit reports via the [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/MoonshotAI/kimi-code/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) template on GitHub. - **Security matters**: Report vulnerabilities privately through [`SECURITY.md`](https://github.com/MoonshotAI/kimi-code/blob/main/SECURITY.md), never via public issues. - **Link issues**: When contributing fixes, ensure your PR references the bug report to comply with [`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/.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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.