Kotonia Agent — VS Code extension

Install (direct download)

Until the Marketplace listing is live, install the VSIX directly.

1. Download kotonia-agent.vsix from the latest build release.
2. In VS Code, open the Extensions view (Cmd/Ctrl+Shift+X) → ⋯ (More Actions) menu → Install from VSIX… → pick the file. No terminal needed — this works on macOS, Windows, and Linux.

If you have the code CLI on PATH (on macOS, enable it via Command Palette → Shell Command: Install 'code' command in PATH), you can instead run:

code --install-extension kotonia-agent.vsix

The engine (kotonia-cli) is downloaded automatically on first use; no manual binary setup is needed for the default (hosted) configuration.

A thin VS Code client over the kotonia-cli Rust engine. The engine does all the work (ReAct loop, tool execution, git-worktree isolation, approval policy, history); this extension is just a UI that speaks the engine's JSON stdio protocol (kotonia-cli --serve).

Architecture

VS Code (extension host)                     kotonia-cli --serve (child)
┌───────────────────────────┐                ┌──────────────────────────┐
│ extension.ts  (lifecycle)  │ ── stdin ───▶  │ stdin reader → turn/appr │
│ engine.ts     (spawn+JSONL)│ ◀─ stdout ───  │ JsonSink (events)        │
│ panel.ts      (webview)    │                │ JsonApproval             │
│ React webview (render UI)  │                │ agent loop               │
└───────────────────────────┘                └──────────────────────────┘

Protocol wire types live in src/protocol.ts, mirroring the Rust side (serve.rs + the Event enum) in the separate kotonia-cli repository. Protocol v2 adds history snapshots and typed editor context; incompatible engine versions are rejected instead of partially working.

Relationship to kotonia-desktop

kotonia-desktop links kotonia-cli as a Rust path dependency and drives DispatchAgent in-process. VS Code extensions run on a TypeScript/Node extension host, so this extension still needs a process boundary (--serve) or a native addon. The target architecture is therefore:

• keep the ReAct engine, provider resolution, worktree setup, history, approval policy, and login helpers in the kotonia-cli library;
• keep kotonia-cli --serve as the thin helper binary for VS Code;
• avoid reimplementing engine assembly in TypeScript. The extension should only spawn/configure the helper and render the protocol.

If CLI and desktop drift, factor the shared setup into a library builder first, then have main.rs, kotonia-desktop, and serve call that same builder.

Where things run (important)

The engine needs bash, git, and (for local models) the LLM servers — all on Linux. The Windows dev machine can't build native Rust (Smart App Control). So run VS Code connected to Linux:

• Remote-SSH to the GPU box (production-like: local models reachable), or
• Remote-WSL locally (use a hosted model: kotonia-llm-basic + API key).

The extension host — and therefore the spawned engine — runs on that remote. kotonia.enginePath resolves there.

Setup

1. Build the engine on the target host: cargo build in the repo root → target/debug/kotonia-cli.
2. In this repository, run npm ci && npm run compile.
3. Point kotonia.enginePath at the binary (e.g. ${workspaceFolder}/target/debug/kotonia-cli, or leave kotonia-cli if on PATH).
4. For hosted models, run Kotonia: Login. The shared ~/.kotonia/daemon.json credential is also used by CLI and desktop.
5. Kotonia: New Chat — the panel starts the engine and shows the handshake.

Dev-run the extension: open this folder in VS Code and press F5 (Extension Development Host).

Settings

Profile and conversation modes

The editor chat header now switches live between Text, Voice, and Avatar. Avatar mode keeps the lip-sync portrait inside the conversation window; Voice plays the same response without rendering video. The selected mode is persisted in kotonia.outputMode.

Open Profile in that same header to edit the display name, tagline, additional system prompt, personality/speaking style, and a local face image. Visual changes apply immediately. Prompt changes are applied when the next new chat starts, because an existing agent session must keep one stable system prompt. A custom face image is also registered as a private Ditto avatar on first use so the generated lip-sync matches the selected portrait.

Current capabilities

• session list/resume with clean user/assistant history restoration;
• active file, selection, visible-file, and diagnostic context sent to CLI;
• in-place coding by default, or preserved/re-attached worktrees with diff review and apply actions;
• clickable Unicode/Windows paths, file:line jumps, URLs in VS Code's Simple Browser, and local HTML preview;
• collapsible long tool output and session-scoped remembered approvals;
• shared CLI login/logout validation and a dedicated Eve Code coding persona;
• Eve as the complete default avatar preset: bundled idle portrait, Qwen3 Ono_Anna voice, and Eve's speaking style, with optional character switching.