VS Code extension

Use grounded code knowledge and tracked delivery inside VS Code. The extension manages the daemon, connects MCP-capable assistants, and adds a chat preview over your own Claude / Codex CLI, pending-document review, and a delivery board.

What it is

The extension provides editor surfaces and manages local integration. Models run through the configured local provider or your existing CLI sessions; the daemon owns indexing and storage.

Privacy. Graph storage and embeddings are local. Cloud reasoning, including configured background summaries, sends context through the Claude / Codex CLI; authentication stays with those CLI sessions. Every write into a host-owned config or rules file is marker-delimited and replace-only, so it preserves your surrounding content and is fully reversed on uninstall.

Requirements

RequirementWhy
VS Code 1.141+Stock Visual Studio Code (or a compatible fork such as Cursor). The extension activates on startup; daemon installation and workspace setup are offered through onboarding.
An AI host or CLIUse an authenticated Claude / Codex CLI for the built-in chat preview, or an MCP-capable host for external assistant integration. The extension can register insrc's MCP tools with supported hosts.
The insrc daemonThe backend the extension talks to. It is installed on first use (see onboarding below); no manual step needed.
Node ≥22.13.0 + gitUsed by the daemon and its installer to clone and build the daemon into ~/.insrc/.

Install

A · VS Code Marketplace (recommended)

Open the Extensions view (⇧⌘X / Ctrl+Shift+X), search for insrc, and click Install — or install insors.insrc-vscode from the Marketplace page. Updates arrive like any other extension.

B · Install from a .vsix (pre-release / internal)

Build the package (see building from source) — a single insrc-vscode-<version>.vsix — then install it directly:

Extensions view → ⋯ → Install from VSIX… and select the built file, or from a shell: code --install-extension insrc-vscode-<version>.vsix.

First-run onboarding

Installing the extension does not touch the daemon by itself — setup happens on first activation, as one coalesced flow that prompts for each step independently and only when it is actually needed:

  1. Install the insrc daemon into ~/.insrc/. Accepting runs the bootstrap installer that clones and builds the daemon; if it is already present it is silently kept current instead.
  2. Register this workspace with the daemon (repo.add) so it gets indexed.
  3. Wire your AI host (Claude Code, Cursor, …) so insrc's MCP tools are available to your assistant.
Skipped a prompt? Every action is also a durable Command-Palette command: insrc: Install daemon / Start / Stop / Restart / Update daemon, insrc: Wire AI hosts, and insrc: Register workspace. Skipped setup actions remain available from the Command Palette.

How it works

Once a workspace is registered, you keep using your assistant exactly as before — the extension just makes it far more grounded:

In the editor

Beyond the invisible wiring, the extension adds a small set of native surfaces so you can drive and inspect insrc without leaving VS Code or dropping to a shell:

Chat preview

Run insrc: Open chat to work through your own Claude / Codex CLI in an editor panel. The preview is enabled by default through insrc.chat.enabled. Choose where edit diffs appear with insrc.chat.diffView.

Pending-document review

Run insrc: Review pending documents to read tracked artifacts and leave review comments. Review and approval remain explicit steps in the tracked workflow.

Delivery board

Run insrc: Open delivery board to inspect tracked work and its delivery state inside the editor.

Keeping the daemon current

On activation (only when the daemon is already reachable) the extension compares the installed daemon's commit against its upstream and, on drift, offers an Update / Dismiss notification that updates the daemon in place on your OK; updating the extension itself brings the daemon current automatically. A failed update surfaces once with the reason — nothing is retried or rolled back, because the daemon owns its own state.

After a successful update the extension nudges you to Reload Window so the insrc MCP connection reconnects to the freshly-updated daemon. A claude / codex session running outside the editor needs a manual restart instead — reloading the window respawns the editor's own MCP host, not an external CLI.

Clean removal

All of the extension's writes into host-owned files are reversible:

Build from source

The extension lives in-repo under vscode-plugin/. It bundles with esbuild to a self-contained .vsix that inlines the shared IPC client and marks vscode external (shipping no repo source):

bash
$ cd vscode-plugin
$ npm install
$ npm test          # the node:test (tsx --test) suite — the local gate
$ npm run bundle    # esbuild → out/extension.js + out/uninstall.js (CJS)
$ npm run package   # @vscode/vsce package → a single .vsix
Publishing is a deliberate, manually-triggered action — never a per-push CI job — and targets the VS Code Marketplace only: bump the version in package.json, then run the vscode-plugin GitHub Actions workflow (workflow_dispatch), which bundles, packages and vsce publishes using the VSCE_PAT secret.

Where next