Known Issues with Kimi-CLI: Critical Bugs and Workarounds

Kimi-CLI suffers from Windows path normalization failures, environment variable loading errors, sub-agent race conditions, and MCP authentication token leakage in debug logs.

Kimi-CLI is a Python-based command-line interface developed by MoonshotAI for interacting with the Kimi AI assistant. While the tool provides powerful async capabilities and sub-agent orchestration, the codebase contains several recurring stability issues that affect Windows users and concurrent workflows. Understanding these known issues with kimi-cli helps developers implement proper safeguards and avoid data corruption in production environments.

Windows Path Handling Failures

On Windows systems, the path normalization utility fails to handle mixed path separators correctly. When users provide paths containing both forward slashes and backslashes, the [windows_paths.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/windows_paths.py) module raises FileNotFoundError exceptions instead of resolving the file location.

The issue stems from the drive letter normalization logic in src/kimi_cli/utils/windows_paths.py not accounting for mixed-separator input received from the UI or shell.

from kimi_cli.utils import windows_paths

# Correct usage to avoid the separator bug

safe_path = windows_paths.normalize(r"C:\Users\Alice\my file.txt")

# Avoid passing raw strings that contain both '/' and '\\'

Environment Variable Loading Errors

The CLI relies on specific environment variables such as KIMI_NOW, but the [envvar.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/envvar.py) utilities raise generic KeyError exceptions when required variables are absent. Rather than aborting with a descriptive message, the CLI often prints warnings and continues execution with undefined or default values, leading to unpredictable behavior.

from kimi_cli.utils import envvar

# Use the safe getter with fallback to prevent KeyError

KIMI_NOW = envvar.get_str("KIMI_NOW", fallback="2024-01-01T00:00:00Z")

Sub-Agent Persistence Race Conditions

When multiple sub-agents resume concurrently, the SubagentStore in [src/kimi_cli/subagents/store.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py) writes overlapping JSON files. This corruption occurs because the persistence layer lacks file-locking mechanisms during concurrent write operations, causing state data to become interleaved or truncated.

To prevent state corruption, serialize sub-agent creation rather than spawning them simultaneously:

# When spawning multiple sub-agents, serialize their creation

await subagent_store.create_one_by_one([spec1, spec2, spec3])

Async Tool Deadlocks and Dangling Coroutines

The Toolset class in [src/kimi_cli/soul/toolset.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py) executes tool calls sequentially but fails to cancel pending async tasks when the main event loop interrupts. This leaves dangling coroutines that consume memory and may block subsequent tool invocations, effectively deadlocking the session.

Always respect cancellation tokens in custom tools to ensure proper cleanup:

async def my_tool(context, cancel_token):
    try:
        await asyncio.wait_for(long_running_op(), timeout=10)
    except asyncio.CancelledError:
        # Clean up resources here before re-raising

        raise

Session Error Recovery and Context Duplication

After exceptions occur, the session recovery logic in [src/kimi_cli/session.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py) attempts to reopen connections but forgets to reset the Context checkpoint in [src/kimi_cli/soul/context.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py). This oversight causes duplicated messages to appear in the UI, creating confusion about the actual conversation state and potentially leading to incorrect AI responses based on repeated context.

Security Vulnerabilities in Logging

Two critical logging issues affect production deployments:

MCP Token Leakage: The OAuth flow in [src/kimi_cli/mcp_oauth.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp_oauth.py) writes raw authentication tokens to debug logs when KIMI_DEBUG is enabled. Third-party log collectors may capture these sensitive credentials, creating a security exposure in centralized logging systems.

# Disable debug logging of sensitive tokens

import os
os.environ["KIMI_DEBUG"] = "0"

Windows Console Encoding: The loguru configuration in [src/kimi_cli/utils/logging.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py) uses ANSI color codes that Windows terminals may not interpret correctly, resulting in garbled output or unreadable error messages on older Windows versions.

Test Suite Flakiness on CI Runners

The end-to-end tests in tests_e2e/, particularly [test_wire_real_llm.py](https://github.com/MoonshotAI/kimi-cli/blob/main/tests_e2e/test_wire_real_llm.py), depend on precise timing for background server initialization. Under heavy CI load, these tests fail intermittently due to race conditions in test setup rather than actual code defects, complicating automated quality assurance.

Summary

• Windows path handling in src/kimi_cli/utils/windows_paths.py fails with mixed separators, requiring normalized input strings.
• Environment variables without fallbacks in src/kimi_cli/utils/envvar.py cause runtime KeyError exceptions.
• Sub-agent storage in src/kimi_cli/subagents/store.py lacks concurrency controls, necessitating serialized creation to prevent JSON corruption.
• Async tools in src/kimi_cli/soul/toolset.py may deadlock because the toolset does not cancel pending coroutines on interruption.
• Session recovery duplicates messages when src/kimi_cli/session.py fails to reset src/kimi_cli/soul/context.py checkpoints.
• Security risks include MCP token exposure in src/kimi_cli/mcp_oauth.py debug logs and Windows console encoding issues in src/kimi_cli/utils/logging.py.
• CI stability suffers from timing-dependent e2e tests in tests_e2e/ that fail under load.

Frequently Asked Questions

How do I fix FileNotFoundError on Windows when using Kimi-CLI?

Ensure all paths passed to the CLI use consistent Windows separators. Use the windows_paths.normalize() function from src/kimi_cli/utils/windows_paths.py to sanitize user input, and avoid mixing forward and backward slashes in path strings that originate from shell auto-completion or drag-and-drop operations.

Why does my Kimi-CLI session show duplicate messages after an error?

This occurs because the session recovery logic in src/kimi_cli/session.py reopens connections without resetting the context checkpoint in src/kimi_cli/soul/context.py. Restart the CLI completely after critical errors to clear the corrupted state rather than relying on the automatic recovery mechanism.

Is it safe to enable KIMI_DEBUG in production environments?

No. Enabling KIMI_DEBUG causes src/kimi_cli/mcp_oauth.py to write raw OAuth tokens to log files. Always set KIMI_DEBUG=0 in production to prevent authentication credential leakage through log aggregation systems.

What causes sub-agent state corruption in concurrent workflows?

The SubagentStore class in src/kimi_cli/subagents/store.py writes JSON state files without file locking. When multiple sub-agents initialize simultaneously, their write operations overlap. Serialize sub-agent creation using create_one_by_one() to avoid this race condition.

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