Repotory for VS Code

Your local knowledge base, inside your IDE. Repotory keeps what your coding agents learn — why a decision was made, what gotcha you hit, what to do next — in a local, searchable store. This extension surfaces it where you work: load a project's full session context, write a structured handoff when you stop, browse your captured knowledge in a built-in reader, and search everything you ever captured, without leaving VS Code.

One VSIX covers the whole fork family — VS Code, Cursor and Windsurf.

What it does

The knowledge reader

The sidebar is a reader, not a results dump. It opens in a T-shaped layout:

┌──────────────────────────────────────────────┐
│ Repotory · your local knowledge base         │  ← brand header, always visible
├─────────────────────┬────────────────────────┤
│ search box          │  the selected note,    │
│ ┌─────────────────┐ │  in full — markdown    │
│ │ NOTE  FTS5 …    │ │  rendered, opened      │
│ │ NOTE  Deploy …  │ │  right here            │
│ │ TODO  Wiki …    │ │                        │
│ └─────────────────┘ │                        │
└─────────────────────┴────────────────────────┘

• Top — identity and what this is. The brand mark and the one-line pitch, plus the scope the search runs in (project · repository), so you always know which knowledge base you are looking at.
• Left — the thumbnails. One card per hit: kind badge (note / todo), title, and the matched excerpt. Type in the search box (300 ms debounce) or use Repotory: Search Knowledge from the Command Palette; both run the same query through the same path.
• Right — the knowledge, expanded. The first result is selected by default, so the pane is never empty while results are on screen. Selecting a note fetches its full body over repotory_notes_read and renders the markdown (headings, lists, code, links); todos show the matched excerpt, labelled as such. A mermaid fence becomes a labelled diagram card — the source stays visible and editable, and the same note renders as a drawn diagram in the Repotory desktop app. Open in Repotory deep-links the item into the Repotory web UI (/project/<id>?noteId=<id> for a note, ?tab=todos for a todo); Copy puts the note on the clipboard.

The pane follows your editor theme — every surface is a VS Code theme color — so it looks native in light and dark alike.

Maintaining notes without leaving the IDE

The reader is also the editor. A note's detail pane carries three maintenance actions, and the desktop app's note list carries the same ones:

The tidy proposal is generated server-side by the shared service layer (OrganizeNote, twin tool repotory_notes_organize) and writes nothing by itself — the human save is the gate, exactly as in the desktop app.

Keyboard shortcuts

The sidebar's title bar also carries a search button. All five commands remain in the Command Palette; rebind them in Preferences → Keyboard Shortcuts if the defaults collide with yours.

Requirements

• The repotory-mcp binary — install it via Homebrew, Scoop or the GitHub Releases page. It does not have to be on your PATH: the extension resolves it in this order and stops at the first hit — repotory.mcpPath, REPOTORY_MCP_BIN, the extension's own storage, PATH, then the usual Homebrew / Scoop / ~/.local/bin directories. If none matches, "Repotory: Set repotory-mcp Path" opens a file picker. The desktop app is optional; the MCP server alone is enough.
• Optional: a running repotory server for the status-bar health check and the sidebar's project · repository display (set repotory.serverUrl if you changed the port).

First launch

On first activation the extension opens "Repotory: Setup & Diagnostics" instead of a wall of instructions: it shows whether the binary was found (and from where), whether the local service answers, what the current folder resolves to, and whether the MCP client config exists. Each row carries its fix — locate the binary, open the download page, re-run registration, or open the folder.

To wire the MCP server into your AI clients, run "Repotory: Register MCP Server". It executes the bundled repotory-init --with-hook in the extension host (Electron-as-node), so no terminal opens; if that fails, the output channel has the full log and a "run it manually" fallback.

Settings

That is the whole surface. No project id to configure: the extension sends the workspace path and the service resolves it into a project and a repository, so there is no setting to keep in sync with your knowledge base.

Workspace resolution

The extension no longer needs a hand-typed project id. Every command sends the current workspace folder's absolute path (repotory_context, repotory_handoff, repotory_notes_search), and the backend's four-tier path resolver (project → repository, most specific first) works out which project — and which repository inside it — the folder belongs to. The matching rules live server-side on purpose: the MCP tools resolve the same path, and a second implementation in the extension would let the sidebar and an agent's repotory_context disagree about which knowledge a session gets. On load and whenever the workspace folders change, the extension asks the read-only ResolveWorkspacePath binding what the folder is and shows the answer: the sidebar's idle row reads <project> · <repository> (or not in the knowledge base yet when nothing matches), and the status-bar tooltip names the resolved workspace.

When the headless service is not reachable, the scope display stays silent (it does not guess) and the status-bar tooltip reports the reachability failure; the commands themselves still work over repotory-mcp, and any path-based resolution there is done by the same server-side code.

Install

Marketplace: search "Repotory" in the Extensions view, or:

code --install-extension repotory-vscode.vsix

One VSIX works in VS Code, Cursor and Windsurf (use the fork's own CLI: cursor --install-extension …, windsurf --install-extension …).

The extension is a thin client — every answer comes from the same internal/service layer as the Repotory desktop app, read from your local SQLite knowledge base. Nothing leaves your machine.

Development

cd ide/vscode
npm install
npm run compile
# open this folder in VS Code and "Run Extension" (F5), or package:
npx @vscode/vsce package --no-dependencies   # → repotory-vscode-<version>.vsix

Architecture and scope: ADR-0009. The extension calls repotory-mcp over stdio and the loopback-only headless service; zero business logic lives here.