Kimi Code 2 Desktop

A macOS desktop shell for the open-source Kimi Code CLI. Manage local kimi server, chat with sessions, approve tool calls, and run Playbooks — all from a VS Code-style four-zone UI.

Kimi Code 2 Desktop (internal name Kimi Shell) is an Electron + React app that does not bundle or fork the Kimi engine. It drives the user's locally-installed kimi CLI via its kimi server REST + WebSocket API. Bring your own kimi — log in via kimi /login, and this app provides the GUI.

✨ Features

v0.2 — commercial-grade UI polish

• Streaming Markdown via markstream-react (smooth token streaming, no skeleton flicker; final re-render on turn end).
• Professional ToolBubble — collapsed tool calls with lucide icons, tool-token colors, expandable JSON input/output (ported from agent-explorer).
• ChatGPT-style Composer — auto-growing textarea, circular send/stop, ⌘↵ hint, slash-menu stub.
• Inline + panel approvals — pending approvals surface both inline in the chat and in the Aux Panel.
• Radix dialogs & tooltips — accessible Dialog/Dropdown/Tooltip primitives; polished ActivityBar with tooltips + login dot.
• System theme — light / dark / system, persisted to localStorage, reacts to OS changes.
• ⌘K command palette (cmdk) — new session, switch sidebar, restart server, settings.
• Sonner toasts, workspace-grouped sessions with pending badges, responsive Aux Panel (folds < 900px).

v0.1 — core

• VS Code-style layout — Activity Bar · Sidebar · Chat Stage · Aux Panel · Status Bar (resizable).
• Session chat — streaming Markdown replies, thinking blocks, tool-call cards, diff views, plan cards.
• Tool approvals — review shell commands, file diffs, and plans before the agent runs them (shell / diff / plan_review / file / url).
• Playbooks — one-click workflows: code review, write README, refactor plan (YAML-defined, extensible).
• Onboarding — detects kimi on PATH, guides login, picks a workspace folder.
• Settings — restart server, open logs, switch theme, view CLI version.

🧱 v0.2 UI stack

markstream-react (streaming Markdown) · lucide-react (icons) · @radix-ui/react-* (Dialog/Dropdown/Tooltip/ScrollArea/Collapsible) · sonner (toasts) · cmdk (command palette) · clsx + tailwind-merge (cn). Design tokens (--tool-*, --shadow-elevated, --transition-*) live in packages/design-tokens.

🏗 Architecture

kimi-shell/                       pnpm monorepo
  packages/
    design-tokens/                CSS variables (light/dark) + layout constants
    kimi-bridge/                  Wire protocol (React-free, fully tested)
      ├ envelope + types          API envelope parser, ChatBlock union
      ├ EventProjector            WS event stream → chat blocks
      ├ RuntimeManager            kimi server child-process lifecycle
      ├ RestClient                /api/v1 REST (workspaces, sessions, prompts, approvals)
      ├ wire-events               real daemon event.* frame mapper
      ├ WsClient                  /api/v1/ws with bearer subprotocol
      └ version-compat            kimi CLI semver gate
    playbooks/                    3 YAML playbooks + registry + browser-safe copy
  apps/desktop/                   Electron main/preload + React renderer
    electron/                     main process (RuntimeManager, IPC, dialogs)
    src/
      app/                        AppShell, OnboardingFlow, SettingsView
      layout/                     ActivityBar, AuxPanel, ResizeHandle, StatusBar
      sidebar/                    SessionSidebar, WorkspaceSidebar, PlaybookSidebar
      chat/                       ChatView, MessageList, Composer, blocks, DiffView
      approval/                   ApprovalCard, ApprovalQueue, QuestionCard
      playbooks/                  PlaybookCard, PlaybookLaunchDialog
      dialogs/                    NewSession, LoginRequired, UpdateCli
      primitives/                 Button, IconButton, TextField, Badge, Toast

kimi-bridge is React-free and dependency-light — it exposes injectable fetch / spawn / WebSocket seams so it's reusable by web, CLI, or mobile shells.

🚀 Quick start

Prerequisites

• macOS 14+ (arm64 or x64)
• Node.js 22+
• pnpm 11+
• The kimi CLI installed and on PATH

# install
pnpm install

# run the dev app (starts Electron + kimi server)
pnpm dev

First launch runs onboarding: it detects kimi, guides you through /login, and picks a workspace folder.

Build & package

# typecheck + test + bundle
pnpm --filter @kimi-shell/desktop build

# produce the macOS DMG + ZIP
pnpm --filter @kimi-shell/desktop dist
# → apps/desktop/release/kimi-shell-<version>-arm64.dmg

First-time install note: if electron-builder isn't yet in the lockfile, run pnpm install (unfrozen) once so it resolves. Typecheck/test/dev work without it.

🧪 Testing

pnpm test        # 69 tests: kimi-bridge (49) + playbooks (5) + desktop (15)
pnpm typecheck   # strict TS across all workspaces

Desktop renderer tests cover the v0.2 pure logic + components: pairToolBlocks, groupSessionsByWorkspace, AssistantMarkdown (streaming final prop), parseUnifiedDiff, clampWidth, design-token presence.

The kimi-bridge package is fully unit-tested, including a WS contract test (test/contract-fixture.test.ts) that replays a recorded event.* stream through the wire mapper + projector to guard against protocol drift.

To validate against a real daemon:

# requires kimi installed + logged in
kimi server run --port 58627 &
bash scripts/integration-smoke.sh   # healthz → workspace → session → prompt

📐 Design & planning docs

• Design spec — pages, component tree, color tokens, layout
• Implementation plan — 16 tasks with file paths, tests, commit messages

🔒 Security model

• Electron contextIsolation: true, nodeIntegration: false
• Preload exposes a minimal, frozen kimiShell.* IPC surface (no raw ipcRenderer)
• Renderer never touches child_process; native capability flows only through main-process IPC
• External links route to the system browser via setWindowOpenHandler
• Bearer token rides the WebSocket subprotocol (kimi-code.bearer.*)

🗺 Roadmap / out of scope (v1)

• Windows / Linux installers
• Self-hosted accounts or paywall
• Modifying or forking Kimi agent-core
• Built-in terminal emulator (Aux Panel is read-only activity in v1)
• Skills store UI

🤝 Contributing

This is an open-source project. The engine it drives (Kimi Code) is separate; this repo is the desktop shell only. PRs welcome — see the design docs for the component tree and the plan for task structure.

📄 License

MIT — Kimi Code 2 Desktop is an independent project and is not affiliated with or endorsed by Moonshot AI. "Kimi" and "Kimi Code" are trademarks of their respective owners.