CTX VS Code extension
Browses the context that the local CTX engine
extracts for a project. The extension is a thin client: it downloads the engine,
runs ctx init / ctx extract once, starts the local runtime over HTTP, and
writes .vscode/mcp.json so VS Code Copilot can use the project context.
Requirements
- VS Code 1.102 or newer (workspace
.vscode/mcp.json support).
- A trusted workspace on a local folder. The extension is disabled in
restricted mode and in virtual workspaces because it downloads and executes a
local binary.
- A published CTX GitHub Release for your platform. If none is available yet,
set
ctx.enginePath to a local ctx executable (see Settings).
Getting started
- Open the CTX view in the activity bar (or run CTX: Set Up Workspace).
- Accept the one-time confirmation.
- The extension downloads the release for your platform, verifies it against
the published SHA-256 checksums, initializes
.ctx/, extracts project
context, and starts the runtime.
Setup runs when you open the view or run a command — not on every folder open.
Reopening a workspace reuses the engine already in global storage and skips
extraction while the context is current; a runtime left running by a previous
window is adopted instead of being started twice.
Commands
| Command |
Description |
CTX: Set Up Workspace |
Force a full re-install/re-extract and restart the runtime |
CTX: Refresh Context |
Re-extract through the running runtime and refresh the tree |
CTX: Search Context |
Query the runtime's /api/search and show the JSON result |
CTX: Open Dashboard |
Open the runtime's dashboard (/ui) in the browser |
CTX: Set Runtime Auth Token |
Store a bearer token in VS Code SecretStorage |
What it writes
.vscode/mcp.json — a ctx stdio server entry (command points at the
downloaded engine, cwd at the workspace folder). Other servers are
preserved, an existing file is backed up once to mcp.json.bak, and the file
is only rewritten when the entry actually changes..ctx/, .ctxignore and a .ctx/cache/ line in .gitignore — created by
ctx init. Git hooks are not installed by the extension.- The engine itself lives in the extension's global storage and is stamped with
the extension version, so updating the extension refreshes the engine while
normal activations stay offline.
Settings
| Setting |
Description |
ctx.enginePath |
Development override pointing at a local ctx executable. |
ctx.runtimeUrl |
URL of a runtime you start yourself (ctx serve). The managed runtime is discovered automatically and ignores this. |
ctx.authToken |
Deprecated plaintext token for a self-managed runtime. Prefer CTX: Set Runtime Auth Token. |
Development
npm install
npm run compile
npm test
npm run test:edh
npm test compiles the extension, compiles the tests separately, and runs every
*.test.js in out-test. Test sources stay out of the published bundle.
npm run test:edh launches a real Extension Development Host against a generated
scratch workspace and asserts the contributed view, welcome view, title menu,
command registration and the full setup flow (tree contents, runtime health,
refresh and search). It expects the engine binary at ../ctx.exe; the download
path is skipped through the ctx.enginePath override.
To try it, open this vscode-ctx folder as a VS Code workspace and press
F5. Do not run out/extension.js directly with Node — the vscode module
comes from the extension host.
