Zettelgeist for VSCode

Open the Zettelgeist Kanban board, dependency graph, and editable spec detail view inside a VSCode panel. Every "click" is still a markdown edit and a git commit — the extension hosts the same viewer the standalone zettelgeist serve does, just with VSCode as the surface.

Features

• Kanban board with drag-to-any-column writeback — drop a card on any status; the spec's frontmatter status: field is updated and committed.
• Editable spec detail view — requirements, handoff, and lens bodies edit inline; tasks support add / edit / delete.
• Per-card edit modal — set status override, blocked reason, PR URL, branch, worktree path.
• Dependency graph — Mermaid rendering of depends_on edges; click a node to jump to the spec.
• Validation banner — surfaces validate_repo errors at the top of the board.
• Theme follows VSCode — automatically picks light or dark to match your editor.

Commands

| Command palette | What it does | | --- | --- | | Zettelgeist: Open Board | Open the Kanban board in a side panel. | | Zettelgeist: Open in Browser | Spawn zettelgeist serve and open the viewer in your system browser (uses zettelgeist.serverPort). | | Zettelgeist: Regenerate INDEX.md | Rebuild specs/INDEX.md from the current spec set. | | Zettelgeist: Install Pre-commit Hook | Install the pre-commit hook that keeps INDEX.md current. |

The extension activates automatically when a workspace contains a .zettelgeist.yaml file.

How it works

The extension hosts the @zettelgeist/viewer bundle in a VSCode webview. A postMessage shim injected into the webview translates the window.zettelgeistBackend calls into messages the extension host answers using:

• @zettelgeist/core for parse / derive / validate / regen.
• @zettelgeist/fs-adapters for disk reads.
• gray-matter + js-yaml for frontmatter merges.
• git (via execFile) for the commit step after each mutation.

Every mutation produces one commit, exactly like zettelgeist serve. There is no in-extension state — close the panel, reopen it, everything loads from disk.

Configuration

All settings live under the zettelgeist.* namespace. Open the VSCode Settings UI and filter by "zettelgeist", or edit settings.json directly.

| Setting | Type | Default | Effect | | --- | --- | --- | --- | | zettelgeist.theme | auto, light, or dark | auto | Viewer theme. auto follows the VSCode color theme. | | zettelgeist.defaultView | board, graph, or docs | board | Which view the panel lands on when opened. | | zettelgeist.autoOpenBoard | boolean | false | Automatically open the board when a workspace containing .zettelgeist.yaml is loaded. | | zettelgeist.serverPort | number | 7681 | Port used by Zettelgeist: Open in Browser when spawning zettelgeist serve. Change if 7681 conflicts with another local service. | | zettelgeist.serverHost | string | 127.0.0.1 | Host the external-browser server binds to. Defaults to localhost-only; set to 0.0.0.0 to share over the LAN. |

The extension's own panel (the webview) doesn't use a port — it loads the viewer bundle directly through VSCode's vscode-webview:// scheme. The port settings only apply to Open in Browser, which spawns the standalone zettelgeist serve and opens the URL in your system browser (handy for screen-sharing, dual-monitor setups, or showing a non-VSCode reviewer).

Requirements

• A workspace folder containing a .zettelgeist.yaml file.
• git available on PATH (the extension shells out for the commit step).

Development

pnpm install
pnpm --filter @zettelgeist/viewer build
pnpm --filter @zettelgeist/vscode-extension build

In VSCode: open packages/vscode-extension, press F5 to launch a development host with the extension loaded.

License

Apache-2.0. See LICENSE and NOTICE.