istari AI

A VS Code companion extension for the istari CLI - a general bridge between the editor and the CLI over a local socket. You can run the workflows as guided commands (no CLI typing), approve or deny istari's gated actions, watch its live progress and report, and steer a running session from VS Code instead of the terminal; more interactions can be added over the same socket.

Guided commands

Run any workflow from the Command Palette (Ctrl/Cmd+Shift+P) under the istari category - a short prompt sequence assembles the exact CLI invocation for you, so you never hand-type a subcommand, flag spelling, or enum value:

Extra entry points:

• Source Control view → Review Local Changes reviews the current worktree in one click, targeting the repo the SCM view points at (multi-root safe).
• Editor context menu → istari: Review Ticket appears when you have a selection, prefilling it as the ticket id.

The quality picker for PR/ticket reviews maps to the CLI's refine model: Standard (the default one round), Fast (--fast), or Refine 2-5 (--refine N). The PR/ticket review commands use istari.defaultModel (below) for --model; plan-review uses it for --architect-model; env-check and init never receive it.

The review commands (Pull Request / Ticket / Plan) hand off to an @istari chat run, so the whole run - progress, approvals, questions, and the final report - renders in one chat response; env-check / init launch in a task terminal. Everything binds the same window-level socket, so only one review runs at a time; a quick env-check or init can run alongside it.

How it works

While this extension is active it exports ISTARI_AI_SOCKET into the window's integrated terminals, so any istari run started here binds the socket automatically - no --approval-socket flag needed (passing the flag still works and wins). istari sends each run-time question - a permission approval, a timeout continue/stop, an ask_user question, or an inbound elicitation - over that socket as a versioned ui_request; the extension renders it in the @istari chat response with buttons or an editor form and sends a complete ui_response straight back. There are no modal popups.

With no chat monitor, the extension surfaces a non-modal notification; opening @istari /watch later re-renders every unanswered request for the live socket connection. Closing a monitor therefore never loses a question. A startup version handshake rejects a mismatched CLI/extension pair with one message and falls back to the terminal rather than mis-rendering. Malformed handshake, request, question, code-block, and stream fields are rejected before reaching the UI. Well-formed future request categories still use the generic form. If another terminal-started review tries to bind the same Unix socket path, it does not steal the active chat session; it falls back to terminal prompts. The full message contract is the Run UI protocol.

sequenceDiagram
    participant istari
    participant Socket as .istari/istari.sock
    participant Chat as @istari chat

    istari->>Socket: hello (version)
    Chat->>Socket: hello_ack + ui_available
    istari->>Chat: ui_request {kind, questions, codeBlocks}
    Chat->>istari: ui_response {action, answers}
    Note over Chat: rendered as chat buttons

Usage

1. Build and install this extension (see Development below).

2. Open a terminal in this window and run istari normally - no flag needed:

   istari ticket-review <jira-url>
   

   (Terminals opened before the extension activated won't have the env var yet; open a fresh one. The istari: Run istari in a terminal command also works.)

3. The status bar shows istari: connected once linked. Watch the run with @istari /watch; approvals and questions then render in that chat response.

Chat: watch, steer, and run

The @istari chat participant reuses VS Code's built-in chat - no separate UI:

• @istari /watch - stream the running agent's progress and report here.
• @istari /reasoning - compatibility command; raw reasoning text is no longer streamed, so it points you to /watch or /report.
• @istari /report - stream only the report/output and the final result.
• @istari /run <args> - start a run in a terminal and stream it here for ticket-review, pr-review, plan-review, or code-review (e.g. /run --capabilities read,verify code-review --staged). Global options precede the subcommand.
• @istari <message> - steer the run: the message is queued and folded into the agent's next pass (istari can't interrupt a pass mid-flight, so it applies at the next draft/repair/refine/steer pass). Steering never changes permission decisions.

Streaming into chat needs an open chat turn, so start with /run (or invoke /watch while a run is active). While a monitor is watching, istari's approvals and questions render in that chat response. Simple choices use buttons; structured elicitation and multiple required fields use the request's Answer action, which collects the whole response before submitting it. A simple single-text question also accepts @istari req:<id> <answer>. Cancel the chat response to stop watching; a later /watch restores any unanswered request for the live socket connection.

CI / headless: omit the extension and use --yes (approve-all) or run without a TTY; istari handles non-interactive approval on its own.

On Windows, the default socket setting works without extra configuration: the extension derives a stable named pipe from the full resolved socket path and exports that exact endpoint to istari. Different workspace paths therefore use different pipes. An explicit pipe setting (e.g. \\.\pipe\istari-ai) is preserved. Named pipes cannot use filesystem watchers, so automatic discovery checks once per second; Unix sockets retain event-driven discovery. Disabling istari.autoConnect stops discovery.

Settings

Commands

• istari: Review Pull Request / Review Ticket / Review Plan / Check Environment / Initialize Config - guided workflows (see Guided commands).
• istari: Review Local Changes - one-click local review from the Source Control view.
• istari: Run istari in a terminal - power-user escape hatch: type raw istari args (tokenized and launched as a task; no shell).
• istari: Connect to the istari socket - connect now.
• istari: Disconnect from the istari socket - cancel a pending connection or drop the active one, invalidate pending run-UI requests, and end active chat monitors for that connection. Automatic reconnection stays paused until Connect is invoked or connection settings or workspace folders change. Disconnect does not stop the CLI task or release its single-run guard.

Changing the socket path or workspace folders cancels the old connection and refreshes the endpoint exported to terminals. Existing terminals may need relaunching to pick up the updated environment.

Development

npm install
npm run compile      # or: npm run watch
npm test             # protocol, lifecycle, discovery, argv, tokenizer, manifest

Press F5 in VS Code to launch an Extension Development Host.

CI runs the extension tests on Windows, Linux, and macOS using the Node version in .node-version. The Windows job also exercises a real named-pipe connection; protocol and lifecycle tests do not require a VS Code runtime.

The guided commands assemble argv from a small typed table (src/commands.ts), whose enum/provider values are drift-guarded against the CLI: cli-manifest.json is a committed snapshot of istari __cli-manifest, and both a Rust test and src/test/manifest.test.ts fail if a flag, enum, or provider changes without regenerating it (UPDATE_MANIFEST=1 cargo test manifest_matches_fixture).

Wire protocol

Line-delimited JSON, one object per line:

// Handshake (istari -> extension, then extension -> istari)
{ "type": "hello", "version": 1, "run": { "id": "run-1", "name": "istari: code-review", "command": "code-review" } }
{ "type": "hello_ack", "version": 1 }

// istari -> extension (one complete request)
{ "type": "ui_request", "version": 1, "id": 1, "kind": "approval",
  "title": "Approval needed", "severity": "warning", "markdown": "Review the action and its risk.",
  "questions": [{ "id": "decision", "kind": "single_choice", "label": "Decision",
                  "options": ["approve", "deny"], "required": true, "default": "deny" }],
  "codeBlocks": [{ "language": "text", "value": "git push origin HEAD" }], "timeoutMs": 0 }

// istari -> extension (live run stream, rendered by @istari chat)
{ "type": "run_start" }
{ "type": "reasoning", "text": "Checking the affected entry points." }
{ "type": "report", "text": "Review output" }
{ "type": "status", "text": "Reading the changed files" }
{ "type": "result", "text": "Final rendered deliverable" }
{ "type": "ui_resolved", "id": 1 }
{ "type": "run_end" }

// extension -> istari (answer; generation belongs to the client connection)
{ "type": "ui_response", "version": 1, "id": 1, "generation": 7,
  "action": "submit", "answers": { "decision": "approve" } }

// extension -> istari (chat monitor availability)
{ "type": "ui_available" } // ui_unavailable when the last monitor closes

// extension -> istari (steering, from @istari chat)
{ "type": "steer", "text": "also cover the error-handling path" }