kb-view
/kb-view — KB Viewer
0. Prerequisites
Check for KB config at .claude/knowledge-base/config.json. If missing, tell user: "KB is not configured. Run /kb-bootstrap to set up your knowledge base." and stop.
1. Suggest Running in a Separate Terminal
Use AskUserQuestion to strongly recommend the user runs the server themselves in a separate terminal window. The server runs continuously and is more responsive when not managed by Claude.
Present the command:
uv run ${CLAUDE_SKILL_DIR}/scripts/serve.py --project-root .
Options:
- "I'll run it myself" (recommended) → Give the command, tell them to open http://127.0.0.1:8787, and stop.
- "Run it for me" → Continue to Step 2.
2. Start the Viewer (fallback)
If the user wants Claude to run it:
- Run in background Bash:
uv run ${CLAUDE_SKILL_DIR}/scripts/serve.py --project-root . - Open browser:
open http://127.0.0.1:8787 - Tell user: "KB viewer running at http://127.0.0.1:8787 — press Ctrl+C to stop."
Custom port: add --port <PORT>.
3. Architecture
scripts/serve.py— ThreadingHTTPServer. Reads KB config, delegates tree building tokb_loader.py, serves markdown with parsed frontmatter and resolved@kb-namelinks. SPA fallback: all non-API paths serveindex.html.scripts/index.html— Single-page app. Sidebar tree, fuzzy search, markdown rendering (marked.js + highlight.js + mermaid),pushStateURL routing, breadcrumb, light/dark/system theme.scripts/graph.js— d3-based knowledge graph. Hierarchical KB layout, hover glow, edge flow animation, controls panel, focus-on-node.
4. API Endpoints
| Endpoint | Description |
|---|---|
GET / |
HTML viewer |
GET /api/tree |
KB tree (JSON via kb_loader.py) |
GET /api/file?path=<rel> |
Markdown file with parsed frontmatter |
GET /api/config |
Raw KB config |
GET /api/search?q=<query> |
Fuzzy search across KB files |
GET /api/graph |
File link graph (nodes + edges) |
GET /* |
SPA fallback (index.html) |
5. Running Tests
uv run ${CLAUDE_SKILL_DIR}/scripts/tests/run_tests.py -v
More from farzadshbfn/knowledge-skills
kb-find
Read-only KB discovery with progressive 4-tier loading and --challenge mode for counter-evidence.
10kb-learn
Manages a personal knowledge base with learning tracking. Modes: (1) learn from articles, (2) learn about topics, (3) fix errors. Uses markdown links with relative paths for cross-references. Maintains a rolling changelog, validates links, and keeps a markdown-compatible knowledge base. When a note reaches ~500 lines, suggests /kb-compact.
9kb-monitor
Monitors KB usage patterns and skill health. Activates when KB access tracking detects frequently-read content that could become a skill, or when user corrections suggest a skill is underperforming. Also triggers on `this isn't working right`, `this skill keeps getting X wrong`, `convert this to a skill`, or `what should become a skill`. Tracks cross-session observations via memory.
8kb-bootstrap
Sets up the knowledge base for a project or initializes the global (god) KB config. Creates the KB config, directory structure, and appends minimal instructions to the project's CLAUDE.md. Run this once when first using KB skills in a new project. Use --global to set up the global read-only KB.
7kb-mint
Mints skills from KB topics, packages skills into plugins, and prepares them for Cowork. Use when asked to create a skill from KB content, convert to a plugin, package for distribution, or make something cowork-ready. Also triggers on `convert this to a skill`, `package as plugin`, `mint a skill`, or `make this a plugin`.
6kb-compact
Compacts KB directories — extracts legacy, unifies terminology, splits oversized notes, fixes indexes, reconciles with skill folders. Default: single directory. Use --deep for recursive bottom-up traversal.
6