koryph VS Code extension

The koryph VS Code extension brings agent-wave visibility and steering into the editor: live agent threads, transcript panels for reading the line of thought, quota burn in the status bar, and worktree navigation — without leaving VS Code.

Source lives at ide/vscode/ (TypeScript, esbuild bundle, zero runtime deps beyond the VS Code API). The extension is not yet published to the marketplace; see Build and side-load below. It installs as a .vsix in under a minute.

The extension shares the same internal/cockpit data layer as the terminal cockpit (koryph tui). Both surfaces show the same numbers from the same source. Pick whichever fits the context — see the cockpit comparison table.

What the extension shows

Agent threads tree view

The Activity Bar gains a Koryph container with one tree: projects → active run → slots, ordered by most-recently-updated.

▸ koryph            run 20260703-091422  running · wave 3 · 2/4 slots
    ● koryph-i2n   running   opus   $0.42   feat/koryph-i2n-completions
    ◐ koryph-fr3.1 review    sonnet $0.18   feat/fr3.1-keepassxc
    ✓ koryph-5ov   merged    sonnet $0.11
▸ ncp_roadmap       (no active run)
▹ Other projects (3 hidden)

Each slot row shows:

Hovering a slot shows: persona, account profile, verified identity, attempt number, and the agent's self-reported status.json step/percentage (labeled as agent-authored and possibly stale — it is not a guarantee).

Tree view badge — count of live agents across visible projects, derived from governor lease files (cheaper and more truthful than a full ledger scan).

Project pinning — projects whose registry root matches a workspace folder are pinned and expanded. All others collapse under "Other projects", controlled by the koryph.showAllProjects setting.

Transcript panels

Click Open transcript on any slot to open a live stream.jsonl panel:

• Assistant text flows as deltas arrive; tool calls collapse to expandable single-line chips; the final result event renders a cost/duration footer.
• Header strip: bead, status, model, attempts, worktree shortcut, Stop and Nudge buttons — a complete cockpit for one agent.
• Tabs within the panel: Transcript, stderr.log, session.log.
• Follow mode toggle for auto-scroll; pause to freeze the view.
• Running spend estimate summed from stream usage fields (approximate; the ledger's authoritative cost_usd appears at completion).

Multiple panels can be open side-by-side. Each retains context when hidden.

Quota status bar

One item per account that owns a visible project with an active run:

⚡ personal 62% 5h · 41% wk

Governor-level coloring (mirrors the engine's default ladder — see Billing and quota):

The thresholds in ide/vscode/src/data/schema.ts mirror the engine defaults (DefaultWarnFraction / DefaultThrottleFraction / DefaultGracefulStopFraction / DefaultHardStopFraction). Live snapshots from koryph quota show --json carry the engine-computed level, which honours any per-account ladder overrides; the extension's client-side quotaLevel() function (used as a fallback when no live snapshot is available) uses the same default fractions.

Click the item for a full quota snapshot and a Calibrate… hint (points at the /koryph-calibrate skill).

Quota data refreshes every koryph.quotaRefreshMinutes (default 5) by running koryph quota show --json asynchronously. Between snapshots the extension reads cached ceiling data from ~/.koryph/quota/<account>.json and shows the age of the data. The UI never blocks on the quota check.

Commands

All commands are available from the Command Palette (⌘⇧P / Ctrl+Shift+P) under the Koryph prefix and from right-click context menus on slot rows in the tree view.

Slot commands

Project commands

Settings

† showAllProjects defaults to true when none of the current workspace folders correspond to a registered koryph project (so the extension is still useful in a window opened for unrelated work), and false otherwise.

Per-account multi-instance behavior

The extension is account-agnostic by construction. It reads files and shells out to koryph; it never reads or writes CLAUDE_CONFIG_DIR and never launches claude. The consequences:

• The same extension build works correctly in both your personal and work VS Code instances (separate --user-data-dir accounts). There is no separate extension per account to install.
• Every dispatch-adjacent action goes through koryph, which rebuilds the agent environment from the registry record and fails closed on identity mismatch — the window's ambient environment never reaches a dispatched agent.
• Project pinning is the only per-window difference. A work-account window opened on project-A pins project-A and collapses others, while a personal window opened elsewhere pins its matched projects — but every project's data remains readable from any window via "Other projects".

This is an intentional consequence of the architecture (Decision 6 in the design document): the extension can never dispatch, so it can never dispatch on the wrong account.

For a full explanation of the account isolation model see IDE integration § 3.

Build and side-load

The extension is not yet published to the VS Code Marketplace. Install from source with vsce:

# One-time prerequisite: vsce (VS Code Extension CLI)
npm install -g @vscode/vsce

# Build the .vsix package
cd path/to/koryph
make ext-build        # runs esbuild bundle + vsce package
                      # outputs ide/vscode/dist/koryph-<version>.vsix

Then install:

# From the command line:
code --install-extension ide/vscode/dist/koryph-*.vsix

# Or from the VS Code UI:
# Extensions (⌘⇧X) → ⋯ → Install from VSIX… → select the .vsix file

The ext-build and ext-test Makefile targets are optional — they no-op with a notice when node is absent, so make gate stays green on Go-only machines.

Running the extension's tests

make ext-test
# or: cd ide/vscode && npm test

Tests are fixture-driven, using real ledger and stream samples from ide/vscode/src/test/fixtures/. They exercise the data-layer parsers that read ledger.json, stream.jsonl, and governor lease files.

Architecture note

The extension is a file-watching client — no daemon, no socket, no event bus in koryph core. It watches the files koryph already writes:

fs.watch with a polling fallback; updated_at fields are the change signal. Every mutation goes through the koryph CLI, which owns locking, audit logging (~/.koryph/audit.jsonl), and account verification. The extension never writes koryph state files directly.

See also

• Terminal cockpit (koryph tui) — full six-tab view, works over SSH and headless; no Node.js dependency.
• IDE integration — account isolation, CLI usage from the editor, and cockpit comparison.
• Billing & quota — calibrating the quota governor.
• Design document — architecture, decision log, and bead decomposition for epic koryph-ew2.