Kin for Visual Studio Code

A new foundation for code. Kin is a graph-native code repository for people and AI agents.

kin-editor brings Kin's graph into Visual Studio Code: entity explorer, natural-language semantic search, trace, go-to-definition, graph-backed review, and semantic rename, with live daemon and graph health in the status bar.

The extension does not implement a second index. It delegates queries to the local Kin runtime over MCP and falls back to the kin CLI when that connection is unavailable. Start with Kin, a graph-native code repository for people and AI agents.

Install, set up, query

1. Install Kin and initialize the repository

On macOS or Linux:

curl -fsSL https://get.kinlab.dev/install | sh
exec "$SHELL" -l

cd /path/to/your/repository
kin init .
kin setup --intent editor
kin status

kin init is the slow step and the one everything else rests on. It admits your Git history into the graph, and every panel in this extension reads that graph rather than the files on disk. Run it before kin setup so setup has a repository to check.

Natural-language semantic search additionally needs vectors, which admission does not build. Add them with kin embed. The first run on a machine downloads about 523 MB of embedding model before anything is indexed, so it is worth starting deliberately rather than in the middle of the install. The entity explorer, trace, and name search all answer before that finishes, and kin status reports embedding coverage so you can see where it is.

Use the Kin quickstart for Homebrew, npm, Windows, installer options, and platform limitations.

2. Install the extension

Install from the VS Code Marketplace, search for extension ID firelock.kin-editor, or run:

code --install-extension firelock.kin-editor

The same published extension is available from the Open VSX Registry. Open VSX is a distribution channel, not a claim that every editor fork is a supported client. The documented and tested editor surface here is Visual Studio Code 1.85 or newer.

To build a local VSIX from source:

npm install
npm run package:vsix
# In VS Code, run: Extensions: Install from VSIX...

3. Run the first graph query

1. Open the initialized repository in VS Code and reload the window after the first kin init.
2. Open the Command Palette and run Kin: Setup Workspace. The panel checks the real kin setup status health report rather than fabricating editor-only readiness.
3. Run Kin: Semantic Search (Cmd+Shift+K S on macOS or Ctrl+Shift+K S elsewhere).
4. Enter a question such as where are webhook retries handled and choose a graph entity from the result picker.
5. Put the cursor on a returned symbol and run Kin: Trace Entity to inspect its related and calling entities.

Semantic Search calls Kin's semantic_locate MCP tool when the persistent MCP connection is healthy. Its CLI fallback is graph-backed name-pattern search, not equivalent vector/natural-language retrieval. The status surface labels the active path as MCP or CLI, and the extension never searches files on its own.

Features

• Graph Browser: the graph's entities grouped by namespace and kind, listed by name rather than by folder. An entity whose graph name carries no namespace is grouped under a row that says so instead of being filed under a directory.
• Entity documents (kin://): open an entity and read its body as the graph serves it, with its kind and name in the tab and its signature, provenance and relations in the hover. Edit Entity opens a separate durable draft. Save preserves exact draft text, including empty or temporarily invalid code; Apply Saved Draft explicitly publishes a saved revision through Kin. Nothing here reads a file: when the graph cannot answer, the viewer says which part could not rather than showing bytes the graph never served.
• Graph diagnostics: what the daemon disclosed about the answer, on the entity you are looking at. Degraded producers, a partial answer, call sites the parser saw and the linker resolved into nothing, pending embeddings and the standing fact that enrichment completion is never attested. Set kin.entityViewer to false for the older file-first Entity Explorer, which opens the projected file instead.
• Semantic Search (Cmd/Ctrl+Shift+K S): natural-language retrieval through semantic_locate, with results in a navigable picker. Workspace symbol search (Cmd/Ctrl+T) uses Kin's name-pattern graph search.
• Trace (Cmd/Ctrl+Shift+K T): focal entity and nearby semantic context. The same graph data supports go-to-definition (F12) and hover, which both need the MCP connection. See the runtime notes below.
• Graph Overview (Cmd/Ctrl+Shift+K O): entity count for the active workspace, plus edge, file, and entity-kind counts when the daemon reports them. States the graph can be in, such as unreachable or still indexing, are named rather than shown as zeros.
• Review (Cmd/Ctrl+Shift+K V): report-only Kin review surfaced as gutter decorations, diagnostics, and the Kin Review output channel.
• Rename (F2): a Kin rename plan for the selected entity and its graph references.
• Status Bar: indexed entity count, or an honest not initialized or unavailable state. Click it for the overview. Kin: Show Status is what reports the active MCP or CLI path and the graph state.
• Multi-root workspaces: commands resolve the active file's owning workspace before selecting its Kin client. The entity explorer and the status bar follow the first Kin-initialized folder in the workspace.

Editing and recovering entity drafts

Open an entity in the Graph Browser and run Kin: Edit Entity. The daemon saves the original source and editing base, then opens an editable kin:// draft. Save writes durable editing state; it does not change published repository source. The draft status bar distinguishes unsaved text, saved text and an Apply receipt.

Run Kin: Apply Saved Draft after saving. Kin checks the original source base under its publication lock. A stale or invalid draft stays saved; use Compare Draft with Current Source, then New Draft from Current Source to choose the changes to carry into a fresh draft. The new draft starts with current source; copy only the changes you want. Old drafts and pending requests remain retained.

A timeout may hide a successful Save or Apply. Retry the same operation: the editor retains its exact invocation before dispatch. Resume Interrupted Apply re-registers the original session when a daemon restart expired it. A recovered receipt names its applied revision; newer saved text may still be unapplied, and an old receipt does not certify the repository's present contents.

Open Saved Draft lists retained drafts, including those whose entity no longer exists. Recover Saved Draft Revision reads an explicit earlier revision even when the latest record is corrupt. Recovery revisions are read-only. Source refreshes never overwrite draft tabs, and published graph diagnostics are not shown as diagnostics for unfinished draft text. If another editor saved first, the revision conflict preserves your buffer; compare and choose a fresh draft.

Draft editing requires an authenticated local daemon with durable draft support. An old daemon, unsupported storage, or a truncated/historical source read keeps the document readable without offering a Save guarantee. The daemon reports its storage limits; raising a configured limit and restarting permits the same refused request to be retried. No prior draft is evicted to make room.

Runtime behavior and settings

With kin.mcpEnabled at its default, the extension launches kin mcp start on activation for each initialized workspace. That process starts or reuses the repository daemon; there is no separate daemon-start step. Turning the setting off runs one kin CLI subprocess per command instead, and either path needs the local kin binary. If no workspace contains .kin/, every Kin command still appears and guides the user to Kin: Initialize Repository or Kin: Setup Workspace.

Setting	Default	Purpose
kin.binaryPath	auto-detect	Absolute kin binary path. Empty checks ~/.kin/bin/kin and PATH.
kin.mcpEnabled	true	Keep a persistent MCP connection; disable to use one CLI subprocess per command.

Hover and go-to-definition are the exception to that fallback. They fire on every word the cursor touches, so they run only over the MCP connection rather than spawning a subprocess per lookup. With kin.mcpEnabled off, or before the connection comes up, they return nothing and stay quiet. Search, trace, overview, status, review, and rename all keep working over the CLI.

When neither path answers, the status bar reads Kin: unavailable and Kin: Show Status says the runtime could not be reached. Neither surface reports an unreachable daemon as an uninitialized repository.

The extension requires the local Kin CLI and daemon. It does not require a hosted KinLab login, and it does not make the still-upcoming hosted repository connection flow available early.

When initialization admits a repository but reports an enrichment or reopening caveat, the editor keeps that warning visible and offers to reload into the admitted graph. The Kin output channel retains the CLI's explanation and recovery guidance. A failed or interrupted admission does not activate the graph.

Maintaining diagnostic compatibility

The editor translates MCP envelope v2 codes using the public Kin clause registry copied into src/diagnostic-codes.json. It preserves older sentence payloads and explicitly identifies unknown codes or versions. Builds and packaged extensions use that checked-in copy and require no adjacent repository.

After reviewing an upstream envelope change, refresh from its Kin checkout:

node scripts/sync-diagnostic-codes.mjs /path/to/kin
node scripts/sync-diagnostic-codes.mjs /path/to/kin --check

The refresh refuses unsupported versions and partial registries. Review any new coverage-limit labels in src/graph-findings.ts and run the diagnostic and full editor tests before updating the supported contract.

Ecosystem

Surface	Role
kin	Semantic system of record, CLI, daemon, MCP, review, and provenance
kin-vfs	Transparent graph-backed filesystem projection
kin-db	Graph storage, indexing, and retrieval substrate
KinLab	Hosted collaboration and control plane

Support

• Kin Discussions
• kin-editor issues
• Kin security policy

License

Apache-2.0.