kimiscope: Instructions file for Codex

KimiScope

Standalone desktop UI for Kimi Code — a Tauri 2 app that renders rich session UI (streaming, thinking, todos, tool cards with diffs, subagents, approvals, usage) on top of the kimi daemon's local REST + WebSocket API. It contains no agent logic; sessions live in the daemon (kimi web), the app is a disposable renderer.

Fresh machine bootstrap (agent-executable)

To set up KimiScope on a new Windows machine, an agent can do everything with these steps (verify each before continuing):

1. Node.js: winget install OpenJS.NodeJS → verify node -v and npm -v.
2. Kimi CLI: npm install -g @moonshot-ai/kimi-code → verify kimi --version.
3. Login: kimi login (device-code flow; needs the user to approve in a browser once) → verify ~/.kimi-code/credentials exists.
4. uv (hands): winget install astral-sh.uv or pip install uv → verify uv --version.
5. Install KimiScope from src-tauri/target/release/bundle/ (or npm run tauri build from source with Rust present). The app auto-starts the server (kimi web --no-open; kimi server run pre-0.28) and reads ~/.kimi-code/server.token — verify curl http://127.0.0.1:58627/api/v1/healthz after first launch.
6. MCP servers (optional powers): write ~/.kimi-code/mcp.json (template in README), then restart the daemon. All servers self-download on first use. GitHub tools additionally need winget install GitHub.cli + gh auth login, then this entry (token from gh auth token): "github": { "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer <token>" } } Logged-in browser additionally needs: "playwright-personal": { "command": "npx", "args": ["-y", "@playwright/mcp@latest", "--browser", "msedge", "--user-data-dir", "%LOCALAPPDATA%\\KimiScope\\edge-agent-profile"] } (create the profile dir first; the user logs into sites once in its window).

Architecture

• Daemon: kimi web --no-open serves REST on http://127.0.0.1:58627 + WS on ws://127.0.0.1:58627/api/v1/ws, bearer auth (0.28+: foreground process; 0.27 and earlier: kimi server run, self-daemonizing). Token is persisted in ~/.kimi-code/server.token (one per home, shared by all instances). Port discovery: ~/.kimi-code/server/instances/*.json (0.28+, may be stale — always probe the port), falling back to ~/.kimi-code/server/lock (0.27) and the default. Busy default port ⇒ 0.28 takes the next free one and records it in its instance file. API specs: reference/openapi.json, reference/asyncapi.json (regenerate types with npm run gen:api).
• Rust side (src-tauri/src/lib.rs): thin — ensures the daemon runs, hands {baseUrl, wsUrl, token} to the frontend via the get_connection_info command. Nothing else.
• Frontend (React 19 + TS + Vite + Tailwind v4 + zustand): talks to the daemon directly.
  • src/api/ — REST client (client.ts), WS client (ws.ts, auth via Sec-WebSocket-Protocol: kimi-code.bearer.<token>, the only browser-feasible mechanism), event types (events.ts).
  • src/state/ — store.ts (zustand, per-session state + frame reducer), sync.ts (socket lifecycle, snapshot→subscribe SessionSync, history pulls, notifications).
  • src/components/ — SessionList (workspaces), ChatView (messages/streaming), ToolCard (per-tool renderers incl. diffs + subagent panels), ThinkingBlock, ApprovalBar, QuestionDialog, InsightRail (todos/usage), Composer (+ CommandMenu / popup), ErrorSurface.