How to Debug Code Generated by kimi-cli: Interactive Shell Commands and CLI Flags

The kimi-cli provides built-in debugging utilities including the interactive /debug command for inspecting conversation context, the --debug CLI flag for verbose logging, and checkpoint rollback to isolate failures.

Debugging AI-generated code requires visibility into the agent's internal reasoning and tool execution. The kimi-cli from the MoonshotAI/kimi-cli repository offers comprehensive debugging tools that let you inspect the full conversation history, trace tool calls, and revert to previous states. These capabilities allow you to step through exactly how the LLM generated specific code blocks and identify where the generation went wrong.

Using the Interactive /debug Command

Located in src/kimi_cli/ui/shell/debug.py, the /debug command launches an interactive Rich-based pager that renders the complete internal state of the current session. When executed within the kimi-cli shell, it pulls the history list from the active KimiSoul instance (app.soul.context.history) and displays a formatted view of the Context object defined in src/kimi_cli/soul/context.py.

The debug view presents:

• Total message count and token usage statistics
• Checkpoint metadata and the file path storing the context
• Each message with role-specific syntax highlighting, including system tags and tool-generated content like images or audio

If no messages have been processed, the command displays a concise panel indicating an empty history.

Inspecting Tool Calls and Generated Content

Within the /debug pager, tool interactions are displayed in dedicated panels labeled Tool Call. Each panel shows the function name being invoked, the unique call ID, and JSON-formatted arguments. This formatting makes it easy to spot malformed inputs or incorrect parameters that caused the generated code to fail.

# Example debug output showing context inspection:

┌───────────────────────────────────────────────────────────────────────┐
│ #1 USER                                                            │
│   Hello, generate a Python script that prints "Hello World".        │
├───────────────────────────────────────────────────────────────────────┤
│ #2 ASSISTANT                                                       │
│   ```python                                                         │
│   print("Hello World")                                              │
│   ```                                                               │
├───────────────────────────────────────────────────────────────────────┤
│ #3 TOOL CALL                                                       │
│   Function: python_exec                                            │
│   Call ID: 42                                                      │
│   Arguments:                                                       │
│   {                                                                 │
│     "code": "print(\"Hello World\")"                                 │
│   }                                                                 │
└───────────────────────────────────────────────────────────────────────┘

Command-Line Debugging Flags

For tracing issues at startup or during automation, use the --debug flag when launching kimi-cli. This flag, parsed in src/kimi_cli/cli/__init__.py, sets the internal logger to DEBUG level and prints full Python tracebacks for any uncaught exceptions.

To enable persistent debug logging across sessions, set KIMI_LOG_LEVEL=debug in your ~/.kimi/config.toml configuration file. This captures all internal logger.debug calls, including context restoration events, checkpointing operations, and tool loading sequences handled by the logging utilities in src/kimi_cli/utils/logging.py.

# Run the CLI with debug logging enabled

kimi run my_agent --debug

Low-Level Wire Protocol Inspection

For debugging the communication between the UI and agent runtime, use the /wire slash commands. Implemented in src/kimi_cli/wire/protocol.py, these commands expose raw JSON-RPC messages exchanged between components:

• /wire:dump: Exports raw JSON-RPC messages exchanged during the session
• /wire:replay: Replays previous wire protocol interactions

This is useful when debugging serialization issues or verifying that tool results are being correctly transmitted back to the LLM.

Checkpoint Rollback for Isolating Failures

The Context class in src/kimi_cli/soul/context.py provides checkpoint functionality that lets you save and restore session states. To revert programmatically:

from kimi_cli.soul.context import Context

# Restore the session to the first checkpoint

await ctx.revert_to(0)

You can also manage checkpoints interactively using the /checkpoint create and /checkpoint revert <id> shell commands. Create a checkpoint before running uncertain code generation, then revert instantly if the output is corrupted.

Typical Debugging Workflow

1. Launch with debug mode: Start the CLI using kimi run my_agent --debug to ensure full tracebacks and debug logging are active.
2. Reproduce the failure: Trigger the code generation that produces errors or unexpected output.
3. Inspect context: Enter /debug in the interactive shell to review the conversation history, token counts, and tool call arguments in the Rich pager.
4. Isolate with checkpoints: If a specific generation step introduces errors, create checkpoints before experimental prompts and use /checkpoint revert <id> to roll back immediately.

Summary

• The /debug command in src/kimi_cli/ui/shell/debug.py provides an interactive Rich pager for inspecting conversation history, tool calls, and token usage.
• Use the --debug CLI flag to enable traceback printing and set log levels to DEBUG via src/kimi_cli/cli/__init__.py.
• Configure KIMI_LOG_LEVEL=debug in ~/.kimi/config.toml for persistent verbose logging of context operations.
• Inspect low-level JSON-RPC communication using /wire:dump and /wire:replay from src/kimi_cli/wire/protocol.py.
• Rollback to previous states using ctx.revert_to(id) programmatically or /checkpoint revert interactively to isolate faulty code generation.

Frequently Asked Questions

How do I enable debug mode when starting kimi-cli?

Append the --debug flag to your command, such as kimi run my_agent --debug. This configures the logger to output DEBUG level messages and ensures full Python tracebacks are printed for any exceptions.

What information does the /debug command display?

The command renders a paginated view of the current Context, showing the total message count, token usage, checkpoint data, and a formatted history of all interactions including system messages, user prompts, assistant responses, and tool call details with JSON arguments.

Can I automatically save checkpoints before risky operations?

Yes, use the /checkpoint create command before triggering uncertain code generation. If the output is incorrect, immediately run /checkpoint revert <id> to restore the previous state, or call await ctx.revert_to(checkpoint_id) programmatically from your Python scripts.

Where does kimi-cli store its debug logs?

By default, debug logs write to standard error. To customize logging, set KIMI_LOG_LEVEL=debug in your ~/.kimi/config.toml file, which is processed by the logging utilities in src/kimi_cli/utils/logging.py.

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