# Kimi-Code Limitations: 8 Critical Constraints Developers Must Know

> Discover Kimi-Code limitations including synthetic events, iframe access, session ownership, and PDF generation caps. Essential knowledge for developers using MoonshotAI kimi-code.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: deep-dive
- Published: 2026-08-11

---

**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)](https://github.com/MoonshotAI/kimi-code/blob/main/plugins/official/kimi-webbridge/skills/kimi-webbridge/SKILL.md#known-limitations)

**Detection and workaround:**

```typescript
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.

```typescript
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)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/docs/node-sdk-migration.md#known-limitations-and-release-gates)

**Manual lock implementation:**

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

```typescript
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:**

```bat
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)](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)](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.