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

> Debug Kimi-CLI issues effectively with our complete troubleshooting guide. Learn to capture essential logs and trace wire events to quickly resolve failures in the MoonshotAI/kimi-cli tool. Get your CLI running smoothly now.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-25

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py)): Parses flags, loads configuration, and selects the model/provider.
- **App Creation** ([`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py)): Houses system prompts, toolsets, and sub-agent registries.
- **Main Loop** ([`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py)): Stores conversation history, checkpoints, and handles serialization.
- **Toolset** ([`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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:

```python

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/utils/debug_context.py) to extract and pretty-print conversation history:

```python
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:

```bash
python utils/debug_context.py <session-id>

```

### Record Wire Messages

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

```python

# 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:

```bash
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:

```python

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py) | `KimiCLI` initialization, config loading, model selection errors |
| [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py) | Event loop logic, `run()` method, wire message emission failures |
| [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) | Serialization bugs in `to_json()` and `from_json()` |
| [`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/AGENTS.md) | High-level architecture overview |
| [`pyproject.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/file/read_file.py) or [`shell/shell.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.