hyseed

hi, 🌱

Welcome! hyseed is a local-first knowledge base for AI agents — and this is its home inside VS Code. Search your team's decisions, lessons, APIs, and runbooks from the sidebar, open the admin console in a tab, or let Claude Code, Cursor, Cline, and other MCP clients query the same knowledge directly. Everything stays on your machine.

This repository contains the VS Code extension and the product portal. The hyseed.exe runtime is bundled into the extension, so there is nothing else to install.

What you get

• Sidebar search — vault-aware search with mode, result count, filters, and per-vault history.
• Admin console — the full hyseed admin UI in a Webview tab.
• MCP & skills — register the hyseed MCP server and install agent skills for Claude Code, Codex, or Cline.
• Vaults — global vaults plus a per-workspace pin.
• Backup — export/import all documents as Markdown from the ⋯ menu.
• Batteries included — a hyseed.exe is bundled; no separate install is required.

Install

VS Code Marketplace (recommended)

Open hyseed on the Marketplace, or install from a terminal:

code --install-extension limccn.kbmcp-vscode

Reload the window afterwards. Commands appear under hyseed:.

Open VSX

For VSCodium and other VS Code-compatible editors, use hyseed on Open VSX:

codium --install-extension limccn.kbmcp-vscode

Offline VSIX

Download the latest kbmcp-vscode-win32-x64-<version>.vsix from Releases, then:

code --install-extension kbmcp-vscode-win32-x64-<version>.vsix

From source

npm ci
npm run package

resources/hyseed.exe and resources/doc-convert.exe are not stored in git because they make the repository heavy. Download them from the GitHub release into resources/, or point HYSEED_RUNTIME_EXE and DOC_CONVERT_EXE at your own copies. The VSIX already bundles both, so this is only needed for source builds. See resources/README.md.

First run

1. CLI tools (recommended, on by default) — copies hyseed.exe and doc-convert.exe to %USERPROFILE%\.local\bin. PATH is reported, never changed.
2. MCP & skills (optional) — registers the MCP server and agent skills for your AI tools.
3. Data folder — accept the default (%USERPROFILE%\.local\share\hyseed) or choose another. A default vault is created.

The guide opens automatically after a first install or a major/minor upgrade. Reopen it with hyseed: Setup guide, or from Doctor in the admin console.

Important environment variables

hyseed reads a small set of environment variables. VS Code settings win where both exist; the variables are the escape hatch for terminals, other editors, and MCP clients.

Variable	What it does	Default / precedence
KB_MCP_HOME	Data root: vaults, documents, and the SQLite index. The extension passes it to every hyseed child process.	kbMcp.dataRoot → KB_MCP_HOME → data_dir in the runtime config → %USERPROFILE%\.local\share\hyseed
KB_MCP_VAULT	Default vault for the hyseed CLI and MCP server. Pinning a workspace also writes this key into .mcp.json.	kbMcp.projectVault → KB_MCP_VAULT → the runtime's current vault
KB_MCP_CONFIG	Path to the runtime YAML config. The extension reads only its top-level data_dir: line.	%USERPROFILE%\.config\hyseed\config.yaml
KB_MCP_HTTP_TOKEN	Bearer token for the HTTP MCP transport. Required by hyseed serve --transport http, and mandatory when kbMcp.mcpHost is not loopback.	The palette's Serve (HTTP) reads %USERPROFILE%\.hyseed-http-token; the value never appears in the terminal.
KB_INGEST_CONVERTER	Path to doc-convert.exe used by ingest.	kbMcp.converterPath → KB_INGEST_CONVERTER → next to hyseed.exe → ingestion-rt/ in the workspace → the bundled copy
KB_MCP_VSCODE_LOG	Optional file path. Mirrors the extension's output channel to a file for bug reports.	Unset (output channel only)
PATH	Where the hyseed CLI is found. Install CLI tools copies the binaries to %USERPROFILE%\.local\bin and reports whether it is on PATH.	PATH is never edited automatically

For packagers, two build-time variables point npm run package at the runtime binaries:

Variable	What it does	Default
HYSEED_RUNTIME_EXE	Path to hyseed.exe for prepare-runtime	resources/hyseed.exe (or the monorepo sibling build)
DOC_CONVERT_EXE	Path to doc-convert.exe for prepare-runtime	resources/doc-convert.exe (or the monorepo sibling build)

Tip: KB_MCP_HOME is the one that matters most. Point it at a folder to move the whole knowledge base, or set kbMcp.dataRoot if you only want the extension to use a different folder.

VS Code settings

Setting	Default	Meaning
kbMcp.runtimePath	""	Explicit hyseed.exe; empty = auto-detect
kbMcp.adminPort	51888	Preferred admin port; the next free port is used
kbMcp.adminHost	127.0.0.1	Bind address; non-loopback exposes the console (no authentication)
kbMcp.mcpHost	127.0.0.1	MCP HTTP bind address; non-loopback needs a token and firewall rule
kbMcp.dataRoot	""	Explicit data folder; empty = default
kbMcp.projectVault	""	Workspace-pinned vault
kbMcp.converterPath	""	Explicit doc-convert.exe; empty = auto-detect

Upgrading from 0.1.x

0.2.0 retires the old names and locations. On activation, an empty data folder is checked for data left by 0.1.x. Nothing is written until you choose:

This is the beginning of the README. Read the rest at the original. Read the full README ↗