Kimi-Code Limitations: 8 Critical Constraints Developers Must Know

Kimi-Code limitations include synthetic browser events that fail on trusted-event checks, no cross-origin iframe access, single-process session ownership, and a 100 MiB PDF generation cap.

The Kimi-Code repository is a sophisticated, monorepo-based AI-coding agent developed by MoonshotAI. While powerful, its architectural design imposes practical boundaries that affect browser automation, IDE integration, and concurrent usage. Understanding these Kimi-Code limitations helps developers avoid failures and implement proper workarounds.

---

Web Browser Automation Limitations

The WebBridge skill enables browser automation through a local daemon that communicates via the Chrome DevTools Protocol. However, this design introduces significant constraints.

Synthetic Events Cannot Pass Trusted-Event Checks

The WebBridge daemon generates click and fill tools that produce synthetic DOM events with event.isTrusted === false. Websites requiring trusted user interactions—such as banking portals, CAPTCHAs, and fraud detection systems—will ignore these events entirely.

Source file: [plugins/official/kimi-webbridge/skills/kimi-webbridge/SKILL.md](https://github.com/MoonshotAI/kimi-code/blob/main/plugins/official/kimi-webbridge/skills/kimi-webbridge/SKILL.md#known-limitations)

Detection and workaround:

await client.toolCall('click', { selector: '#pay-button' })
  .catch(async err => {
    if (err.message.includes('event.isTrusted')) {
      await client.sendMessage(
        "The target site blocks synthetic clicks. Please click manually, then reply 'done'."
      );
    } else {
      throw err;
    }
  });

Cross-Origin Iframe Access Is Blocked

All WebBridge tools operate exclusively on the top-level frame. The daemon lacks permission to reach into sandboxed, cross-origin iframes, causing click, fill, evaluate, and snapshot operations to fail when targeting elements inside them.

Recommended workaround: Navigate directly to the iframe's source URL in a new tab instead of attempting cross-frame interaction.

const iframeUrl = 'https://example.com/widget';
await client.toolCall('navigate', { url: iframeUrl, newTab: true });

---

VS Code Extension Limitations

The VS Code extension migration introduced several constraints due to its in-process v1 engine architecture running via @moonshot-ai/kimi-code-sdk.

No Cross-Process Session Locking

The VS Code extension shares a single on-disk store with the CLI and TUI, but this store implements no cross-process write lock. Concurrent writes from multiple processes can corrupt the session index.

Source file: [apps/vscode/docs/node-sdk-migration.md](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/docs/node-sdk-migration.md#known-limitations-and-release-gates)

Manual lock implementation:

import { existsSync, writeFileSync, unlinkSync } from 'fs';

const lockPath = `${process.env.KIMI_CODE_HOME}/sessions/${sessionId}.lock`;

if (existsSync(lockPath)) {
  throw new Error('Session is already in use by another process.');
}
writeFileSync(lockPath, process.pid.toString());

// ... run session ...

unlinkSync(lockPath);

Remote Development Environments Remain Unvalidated

Remote SSH, WSL, and Dev Container behaviors lack representative smoke-tests. Edge cases may emerge when the remote Kimi-Code home directory differs from the local configuration, as VS Code's remote extensions resolve paths within the remote container.

Best-Effort Baseline Tracking

The File Changes panel in VS Code stores baselines only in the extension's global storage—not in core session state. Arbitrary Bash mutations or external file edits are not captured, and the core engine does not pause tool execution for VS Code callbacks.

---

Session Storage Limitations

Kimi-Code sessions rely on a plain JSON-line log without any locking layer. This design choice prioritizes single-binary distribution simplicity but creates operational constraints.

Single-Process Session Ownership

Only one process should own a session at any time. Running identical sessions simultaneously in the TUI and VS Code extension risks race conditions and index corruption.

Core implementation: packages/agent-core-v2/src/services/session-index.service.ts

---

Tool-Specific Limitations

100 MiB PDF Generation Cap

The WebBridge save_as_pdf tool enforces a hard 100 MiB size limit on generated PDFs. Requests exceeding this threshold are rejected by the daemon to maintain responsiveness.

Mitigation strategy:

await client.toolCall('save_as_pdf', {
  paper_format: 'a4',
  scale: 0.5,  // Reduce resolution to stay under cap
  path: '/tmp/report.pdf'
});

Windows PowerShell JSON Corruption

PowerShell's built-in curl alias (Invoke-WebRequest) corrupts non-ASCII characters when JSON bodies are passed inline. The WebBridge skill mandates using curl.exe with --data-binary @tempfile.json.

Correct Windows invocation:

set TEMP_REQ=%TEMP%\webbridge-req-%RANDOM%.json
echo { "action":"navigate","args":{"url":"https://example.com"} } > %TEMP_REQ%
curl.exe -s -X POST http://127.0.0.1:10086/command ^
  -H "Content-Type: application/json" ^
  --data-binary @%TEMP_REQ%
del %TEMP_REQ%

---

Model Configuration Limitations

Thinking Effort UI Visibility

The Kimi-Code interface exposes thinking-effort controls only for models declaring support_efforts. When switching to models without this capability, the control disappears and effort tuning is silently disabled—no warning is issued to the user.

---

Why These Limitations Exist

Design principle	Resulting limitation
Security & sandboxing	No trusted events or cross-origin iframe access without explicit user interaction
Single-binary distribution	No heavyweight inter-process coordination for session locking
Legacy compatibility	VS Code extension inherits constraints from original Python architecture
Performance protection	Hard PDF size cap prevents daemon blocking

---

Summary

• Synthetic browser events fail on sites requiring event.isTrusted === true; use manual user prompting as fallback
• Cross-origin iframes are inaccessible; navigate directly to iframe URLs instead
• Single-process session ownership is mandatory; implement manual locks or risk corruption
• VS Code + CLI concurrency is unsupported due to absent cross-process write locks
• Remote development (SSH/WSL/Containers) needs additional validation
• 100 MiB PDF cap requires resolution reduction for large documents
• Windows PowerShell users must use curl.exe with file-based JSON payloads
• Thinking-effort controls are model-dependent and disappear silently for unsupported models

---

Frequently Asked Questions

Can Kimi-Code automate banking websites or CAPTCHAs?

No. The WebBridge daemon generates synthetic events with event.isTrusted === false, which banking portals and CAPTCHA systems explicitly reject. The only workaround is prompting the user to perform the action manually, as documented in [plugins/official/kimi-webbridge/skills/kimi-webbridge/SKILL.md](https://github.com/MoonshotAI/kimi-code/blob/main/plugins/official/kimi-webbridge/skills/kimi-webbridge/SKILL.md#known-limitations).

What happens if I run the same Kimi-Code session in VS Code and the terminal simultaneously?

Concurrent access risks session index corruption because the JSON-line storage lacks write locks. The migration document at [apps/vscode/docs/node-sdk-migration.md](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/docs/node-sdk-migration.md#known-limitations-and-release-gates) explicitly marks this configuration as unsupported.

Why does my Windows PowerShell WebBridge request return garbled JSON?

PowerShell's curl alias invokes Invoke-WebRequest, which corrupts non-ASCII characters in inline JSON bodies. The WebBridge skill requires bare curl.exe with --data-binary @filename.json to preserve payload integrity.

Is there any way to increase the 100 MiB PDF generation limit?

No. The 100 MiB cap is hardcoded in the WebBridge daemon to prevent performance degradation. Reduce scale below 1.0 or split content across multiple PDF requests to stay within the limit.

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