Knowledge Management

Personal board, calendar, sessions, and local agent chat — inside VS Code.

Install: Extensions → Search "Knowledge Management" (publisher zhirafovod) or:

code --install-extension zhirafovod.km-vscode

Then Command Palette → Knowledge Management: Open.

The extension bundles a local daemon. Your data stays in git-backed folders on this machine (~/docs/planning, ~/docs, ~/.sessions by default if you set the settings below). Status → Sync pulls those repos; it never pushes, and it never syncs ~/fleet.

First launch on another Mac

1. Clone stores (skip if they already exist):

git clone git@github.com:zhirafovod/docs.git ~/docs
git clone git@github.com:zhirafovod/sessions.git ~/.sessions

2. Settings (settings.json):

{
  "km.storeRoot": "/Users/<you>/docs/planning",
  "km.kbRoot": "/Users/<you>/docs",
  "km.sessionsRoot": "/Users/<you>/.sessions"
}

3. Knowledge Management: Open. Status → Sync now.

Requires Node 22+ on PATH (the bundled daemon is Node). If nothing is configured, Open reuses the live daemon on :4700 when it is up, otherwise ~/docs/planning when that directory exists. It never starts --demo on reserved ports 4700/4173.

Open with Demo Data always boots an ephemeral demo daemon on --port 0 (does not touch your stores or the live ports).

Commands

Settings

• km.storeRoot — planning store; empty → live :4700 if healthy, else ~/docs/planning if present (not --demo on 4700)
• km.sessionsRoot — --sessions-root when store root is set
• km.kbRoot — --kb-root when store root is set
• km.daemonArgs — full daemon argv for km.open (overrides the three roots). Same as KM_DAEMON_ARGS in the desktop app.
• km.preferLiveUi — default true. If the live app is already running (:4700 + UI :4173), the panel loads that UI so it matches localhost instead of the vsix snapshot. Off, or no runner: bundled UI.
• km.daemonUrl — remote daemon origin (daemon.endpoint). When set, Open connects here instead of spawning. Non-loopback hosts must be HTTPS.
• km.authToken — Bearer token (daemon.apiToken) injected as window.__KM_TOKEN__. Do not enable Settings Sync for this key.

If port 4700 is already the live KM instance, Open reuses it. Remote switch path: docs/remote-daemon.md.

Report bug / feature

The top bar Report cluster (every view) has Bug (data-testid="km-report-bug") and Feature (data-testid="km-report-feat"). Either captures the current shell, current view/selection/filters, daemon health, and implementer phase, then creates a KP task (issue_kind: bug or feature) and opens a new Build chat. Browser captures without a file picker. Neither is auto-queued.

In this webview, a pixel screenshot can fail (CSP img-src + cloned CSS). When that happens KM attaches a fallback PNG of the visible text and, in the webview only, offers a file picker (data-testid="km-report-bug-file"). You can also paste a screenshot into the new chat.

Standalone .app (no VS Code): see desktop INSTALL.

Thin VS Code shell: it does not reimplement the UI. It ensures the daemon is running and opens a webview. window.__KM_DAEMON__ is injected so WsBridge talks to that daemon.

An installed VSIX is self-contained: media/ui + media/daemon/cli.cjs (bundled from packages/daemon/dist/main.js via scripts/bundle-daemon.mjs). F5 in this repo falls back to monorepo-relative paths.

Dev loop

From the monorepo root:

npx tsc -b packages/daemon
npm run build -w @unpolarize/ui
npm run build -w km-vscode

Open this folder (packages/shells/vscode) in VS Code and press F5 (Extension Development Host). In the new window, run Knowledge Management: Open with Demo Data.

If the monorepo is the workspace, launch with:

--extensionDevelopmentPath=${workspaceFolder}/packages/shells/vscode

Package

npm run package -w km-vscode
code --install-extension packages/shells/vscode/km-vscode.vsix

km-vscode.vsix is gitignored. The package script rebuilds, then vsce package --no-dependencies.

Closing the extension host kills any daemon this extension spawned.