kb

A CLI + MCP server that compiles raw notes into an organized personal wiki using an LLM, and exposes that wiki to AI coding assistants like Claude Code and OpenCode.

Notes live as plain Markdown in an Obsidian vault. kb reads unprocessed files, runs them through an LLM, and writes structured wiki articles back to disk. No database — the wiki is the database.

Inspired by the note-taking workflow recommended by @karpathy and built around Obsidian as the note-taking layer.

Screenshot

Requirements

• Go 1.24+
• Obsidian — kb opens notes directly in the app via the obsidian:// URI scheme
• One of: Claude Code, OpenCode, or Codex CLI
• Optional: fd, rg, bat (fallback to stdlib if missing)

Install

go install github.com/alexeira/kb@latest

Or build from source:

git clone https://github.com/alexeira/kb
cd kb
go build -o kb ./cmd/kb

Usage

kb                       # open TUI dashboard
kb init <path>           # initialize a vault at the given path
kb compile               # compile raw notes into wiki articles
kb query "..."           # ask a question against the wiki (streams output)
kb query "..." --out md  # stream answer and auto-save to outputs/<slug>.md
kb lint                  # check for broken links and orphan articles
kb sync                  # git commit and push vault changes
kb open                  # open the vault in Obsidian
kb config                # show current configuration
kb mcp                   # start the MCP server on stdio

kb init does not require Git. If the chosen vault lives inside an existing repository, kb reuses that repository for kb sync. If not, you can keep the vault local-only or opt into Git with kb init --git <path>.

Customizing prompts

kb init writes two workflow files to the vault root:

• workflow.md — controls how raw notes are compiled into wiki articles. Supports {{index}}, {{wiki_dir}}, and {{source_files}} placeholders.
• query-workflow.md — controls how questions are answered. Supports {{question}}, {{index}}, and {{format_instructions}} placeholders.

Edit these files to tune the LLM behavior without touching Go source. If a file is missing, kb falls back to the built-in defaults.

Recommended workflow

The best way to feed kb is Obsidian Web Clipper — the official browser extension that saves any web page directly into your vault as a Markdown note with clean frontmatter (title, source, author, description, tags).

1. Install Web Clipper and configure it to save clippings to your vault's Clippings/ folder
2. Clip articles, docs, or anything worth keeping while browsing
3. Run kb compile — the LLM processes all unread clippings and writes wiki articles to wiki/
4. Source files are tagged processed so they are never recompiled
5. wiki/_index.md is maintained automatically as a taxonomy of all articles

You can also drop files manually into raw/, or use kb ingest <url> to fetch a page from the terminal.

MCP server

kb runs as an MCP server on stdio, exposing 6 tools to AI assistants:

Tool	Description
kb_compile	Compile unprocessed notes
kb_query	Answer questions from the wiki
kb_lint	Check for structural issues
kb_sync	Commit and push changes
kb_ingest	Add a file or URL
kb_status	Vault stats

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["mcp"]
    }
  }
}

OpenCode

See plugins/opencode/ for the OpenCode plugin configuration.

Roadmap

Current state

Feature	CLI	TUI
kb compile	✅	✅
kb sync	✅	✅
kb query	✅ streaming	❌ not yet
kb lint	✅ reports issues	⚠️ display only, no actions
kb ingest <file>	⚠️ copies to raw/, no tag	❌ not yet
kb ingest <url>	❌ raw HTML, no conversion	❌ not yet
MCP server	✅	—
Claude Code plugin	⚠️ untested	—
OpenCode plugin	⚠️ untested	—
Codex plugin	❌ not yet	—

Near term

• Fix ingest — tag ingested files as raw in frontmatter; disable URL ingest until HTML→Markdown conversion is implemented
• Query in TUI — interactive question/answer inside the dashboard
• Lint actions in TUI — act on issues: create missing articles, fix broken links
• Plugin setup wizard — TUI screen to configure Claude Code, OpenCode, and Codex plugins
• Validate plugins — test and polish Claude Code and OpenCode plugin configs

Later

• Ingest URLs — convert HTML to clean Markdown with frontmatter (title, source, author) matching Web Clipper output
• Ingest PDFs and images — extract text and metadata into raw/
• Ingest GitHub repos — clone and extract README + key files
• Codex plugin — parity with Claude Code and OpenCode
• More providers — Cursor, Windsurf, VS Code + Copilot, Zed, Gemini CLI, Kimi CLI
• Smart lint — LLM-assisted fixes: suggest articles for broken links, find cross-article inconsistencies
• Charts output — mermaid diagrams from query results, filed back into wiki/
• Release pipeline — pre-built binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64
• Landing page — with screenshots and install instructions

License

MIT