How to Debug Kimi-CLI Issues: A Complete Troubleshooting Guide

Set LOG_LEVEL=DEBUG or KIMI_WIRE_DEBUG=1 before running any command to capture wire events and tool invocations that reveal the root cause of most Kimi-CLI failures.

Kimi-CLI is an open-source Python-based interactive agent developed by MoonshotAI that combines a Typer CLI entry point with an async runtime and wire-based UI. When errors occur in this complex system, knowing how to debug kimi-cli issues requires understanding the data flow between the soul, context, and UI components.

Understanding the Kimi-CLI Architecture

Before diving into debugging, you need to understand how the components interact. The system consists of several key modules:

• CLI Entry (src/kimi_cli/cli/__init__.py): Parses flags, loads configuration, and selects the model/provider.
• App Creation (src/kimi_cli/app.py): Builds the KimiCLI instance, loads agent specifications, restores context, and creates the KimiSoul event loop.
• Agent Core (src/kimi_cli/soul/agent.py): Houses system prompts, toolsets, and sub-agent registries.
• Main Loop (src/kimi_cli/soul/kimisoul.py): Receives user input, manages the Context, calls the LLM, executes tools, and handles compaction.
• Context (src/kimi_cli/soul/context.py): Stores conversation history, checkpoints, and handles serialization.
• Toolset (src/kimi_cli/soul/toolset.py): Loads built-in tools (shell, file, web) and bridges to MCP tools.
• Approvals (src/kimi_cli/soul/approval.py): Manages pending user confirmations for dangerous actions.
• UI Front-ends (src/kimi_cli/ui/**): Consumes events emitted by the soul via the wire protocol.

The wire protocol (src/kimi_cli/wire/) defines the contract between the soul and UI; most test failures surface here.

Step-by-Step Debugging Methods

Enable Verbose Logging

Start by re-running the failing command with verbose logging enabled. The application uses loguru, which respects the LOG_LEVEL environment variable:

LOG_LEVEL=DEBUG kimi <subcommand>

This outputs each wire event (KimiWireMessage) and tool invocation to stderr, showing exactly where the execution diverges from expected behavior.

Inspect Session Directories

Kimi-CLI persists state in ~/.kimi/sessions/<session-id>/. After a failure, examine these files:

• context.json: Raw conversation history showing the exact messages sent to the LLM.
• wire.log: Chronological dump of wire messages useful for post-mortem analysis.
• subagents/: Persisted sub-agent state; corruption here often explains "resume" failures.

Run the Test Suite

Execute the built-in tests to isolate whether the issue is environmental or code-related:

make test          # Unit tests

make ai-test       # Integration tests with mocked LLM providers

make check         # Lint and type checks (ruff, pyright)

Test failures in tests_e2e/test_wire_errors.py typically point directly to the misbehaving module.

Use Wire-Debug Mode

For detailed wire protocol inspection, enable "wire-debug" mode:

KIMI_WIRE_DEBUG=1 kimi <cmd>

This adds timestamps and pretty-prints wire messages, making it easier to trace UI updates and event emissions.

Debug Tool Calls with PDB

When a specific tool fails, insert a breakpoint directly in the tool implementation. For example, to debug file operations:

# In src/kimi_cli/tools/file/read_file.py

import pdb; pdb.set_trace()

The async runtime will pause execution, allowing you to inspect local variables and the execution state.

Validate LLM Provider Configuration

If the issue relates to token limits, malformed messages, or authentication failures, inspect src/kimi_cli/llm.py and your local configuration at ~/.kimi/config.toml. Verify that model names, API endpoints, and credentials match the provider's requirements.

Replay Sessions with AI-Test

Use the integration test harness to replay recorded sessions against a mock LLM, isolating UI logic from LLM behavior:

make ai-test TEST=tests_e2e/test_wire_real_llm.py

This replays stored wire events, helping you determine whether the bug exists in the UI rendering or the LLM interaction logic.

Diagnostic Code Snippets

When standard logging is insufficient, use these utility scripts to extract internal state.

Dump Context for Analysis

Save this as utils/debug_context.py to extract and pretty-print conversation history:

from pathlib import Path
import json

def dump_context(session_id: str):
    ctx_path = Path.home() / ".kimi" / "sessions" / session_id / "context.json"
    print(json.dumps(json.loads(ctx_path.read_text()), indent=2))

if __name__ == "__main__":
    import sys
    dump_context(sys.argv[1])

Run it with:

python utils/debug_context.py <session-id>

Record Wire Messages

To capture a complete wire dump without modifying the main application:

# utils/record_wire.py

import os
from pathlib import Path
from loguru import logger

def enable_wire_logging():
    log_path = Path.home() / ".kimi" / "wire_debug.log"
    logger.add(str(log_path), level="DEBUG", filter=lambda r: "wire" in r["message"])
    os.environ["KIMI_WIRE_DEBUG"] = "1"

if __name__ == "__main__":
    enable_wire_logging()

Source the environment changes and run your command:

source <(python utils/record_wire.py)
kimi chat "test"
cat ~/.kimi/wire_debug.log | less

Check Sub-Agent Persistence

Verify sub-agent state integrity with this quick check:

# utils/check_subagent.py

from pathlib import Path

def list_subagents():
    base = Path.home() / ".kimi" / "sessions"
    for sess in base.iterdir():
        for sub in (sess / "subagents").glob("*"):
            print(f"{sess.name}/{sub.name}")

if __name__ == "__main__":
    list_subagents()

Key Source Files for Troubleshooting

Understanding these specific files accelerates root cause analysis:

File	Debugging Focus
src/kimi_cli/app.py	KimiCLI initialization, config loading, model selection errors
src/kimi_cli/soul/kimisoul.py	Event loop logic, run() method, wire message emission failures
src/kimi_cli/soul/context.py	Serialization bugs in to_json() and from_json()
src/kimi_cli/soul/toolset.py	Dynamic tool loading, import errors, missing tools
src/kimi_cli/tools/**	Individual tool implementations (shell, file, web)
src/kimi_cli/wire/**	Wire message definitions for "unknown event" errors
tests_e2e/**	End-to-end test failures indicating stack-wide issues
AGENTS.md	High-level architecture overview
pyproject.toml	Dependency version conflicts

Summary

• Set LOG_LEVEL=DEBUG or KIMI_WIRE_DEBUG=1 to capture detailed execution traces.
• Inspect ~/.kimi/sessions/<id>/wire.log and context.json for conversation state and protocol errors.
• Run make test and make ai-test to isolate unit-level versus integration-level bugs.
• Add pdb.set_trace() to specific tool files in src/kimi_cli/tools/ for interactive debugging.
• Verify ~/.kimi/config.toml when encountering LLM provider or authentication issues.
• Use the ai-test harness to replay sessions against mock LLMs and isolate UI from backend problems.

Frequently Asked Questions

How do I enable debug logging in Kimi-CLI?

Set the LOG_LEVEL environment variable to DEBUG before running your command: LOG_LEVEL=DEBUG kimi chat. For wire-specific debugging, use KIMI_WIRE_DEBUG=1 instead, which adds timestamps and pretty-prints the wire protocol messages between the soul and UI components.

Where are Kimi-CLI session files stored?

Session persistence is stored in ~/.kimi/sessions/<session-id>/, where each directory contains context.json (conversation history), wire.log (chronological wire messages), and a subagents/ folder containing persisted sub-agent state. Corruption in these files often causes resume failures or context loss.

What should I check if a specific tool keeps failing?

First, locate the tool implementation in src/kimi_cli/tools/ (e.g., file/read_file.py or shell/shell.py). Insert import pdb; pdb.set_trace() at the entry point to break into the async runtime and inspect arguments and state. Also check src/kimi_cli/soul/toolset.py for dynamic loading errors or missing imports that might prevent the tool from registering.

How do I run integration tests against a mock LLM?

Execute make ai-test to run the integration test suite, which uses mocked LLM providers to test the full stack without external API calls. To run a specific test file, use make ai-test TEST=tests_e2e/test_wire_real_llm.py. This replays stored wire events to isolate whether bugs exist in the UI rendering layer or the LLM interaction logic.

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