kb

A terminal UI for reading a project's knowledge base, plus the Claude Code skill that writes one.

The two halves are deliberately decoupled and share only an on-disk format:

Half	What it does	Lives in
kb	Reads and renders docs/knowledge-base/*.md in a TUI	src/ (this crate)
/knowledge-base	Researches a codebase and writes those files	skills/knowledge-base/

Neither calls the other at runtime. You can use the skill without the viewer (the output is plain markdown that renders on any git forge), or point the viewer at a knowledge base written by hand.

Installing the viewer

Via Homebrew, using this repo as its own tap:

brew tap headscracher/knowledgebase https://git.all4-one.de/Headscracher/KnowledgeBase.git
brew install headscracher/knowledgebase/kb

Or build from source (requires a Rust toolchain):

cargo install --path .

Installing the skill

Copy it into your personal Claude Code skills directory:

cp -r skills/knowledge-base ~/.claude/skills/

Or symlink it, so it tracks this repo as you pull updates:

ln -s "$PWD/skills/knowledge-base" ~/.claude/skills/knowledge-base

Then run /knowledge-base from any project you want documented.

Using it

Run kb in a project that has a knowledge base. It walks upward from the current directory looking for docs/knowledge-base/, the same way git looks for .git, so it works from any subdirectory:

kb            # search upward from the current directory
kb some/path  # search upward from a specific directory

If nothing is found it says so and exits, without taking over the terminal.

Key	Action
← → / h l	Switch section (top tab bar)
↑ ↓ / j k	Switch sub-section (left outline)
PgUp PgDn	Scroll the content pane
/	Full-text search across all sections
q	Quit

The mouse works too: click a tab or an outline entry, scroll the wheel over the content pane, or click the search hint in the status bar.

The file format

Each section is a markdown file with YAML frontmatter. kb reads the frontmatter for the sidebar's freshness markers; the skill writes it so a later run can tell which sections went stale:

---
title: Authorization
last_scanned_commit: 8f3a1c2
last_scanned_date: 2026-08-26
status: complete   # complete | partial | stale
paths_considered:
  - src/auth/**
---

status drives the marker next to each tab: ✓ complete, ~ partial, ! stale, ? unreadable frontmatter. A section whose frontmatter fails to parse still renders its body, with the error shown above it.

Section filenames are fixed (00-overview.md through 09-misc.md, plus a generated README.md index) so both halves agree on what exists without needing a manifest.

Development

cargo test                                                  # viewer tests
bash skills/knowledge-base/scripts/test-stale-sections.sh   # skill script tests

This project documents itself: docs/knowledge-base/ is real output from the skill, so the fastest way to see what kb looks like is to build it and run it here.

License

MIT — see LICENSE.