Kb
A CLI tool and MCP server for managing markdown knowledge bases across coding projects.
Ask AI about Kb
Powered by Claude Β· Grounded in docs
I know everything about Kb. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Agent Knowledge Base
A CLI tool and MCP server for managing markdown knowledge bases across projects. Externalizes project context (CLAUDE.md/AGENT.md) and shared documentation (API docs, specs, workflows) into a central versioned directory, then exposes it to AI coding agents via MCP.
Supports Claude Code, OpenAI Codex, and OpenCode.

Why
- Context files are scattered across repos with no way to share docs between projects
- API documentation gets duplicated - the same API docs copied into 3+ repos
- No version history - when you update project context, the old version is gone
- Large reference docs waste context - 9000-line API docs shouldn't load into every session
kb solves this by centralizing knowledge into ~/knowledge-base/ with:
- Per-project context that replaces in-repo CLAUDE.md files
- Shared docs that multiple projects reference without duplication
- Global shared docs that are available to all projects automatically
- Inline mode to embed shared doc content directly into context.md (loaded at session start without MCP calls)
- Git versioning on every change (auto-committed)
- An MCP server so agents can search, read, and write docs on-demand
- A TUI browser for navigating and assigning refs to the knowledge base interactively
Setup
1. Install
go install github.com/leona/kb@latest
Or download a prebuilt binary from the latest release:
curl -Lo kb https://github.com/leona/kb/releases/latest/download/kb-linux-amd64
chmod +x kb
sudo mv kb /usr/local/bin/kb
Replace kb-linux-amd64 with your platform: kb-darwin-arm64 (macOS Apple Silicon), kb-darwin-amd64 (macOS Intel), kb-windows-amd64.exe.
2. Initialize the knowledge base
kb init
This creates ~/knowledge-base/ with:
kb.ymlβ configuration fileshared/β directory for shared documentsprojects/β directory for per-project knowledge.git/β version history (auto-managed)
To use a different directory:
kb init --dir ~/my-knowledge-base
Then set KB_ROOT in your shell config:
export KB_ROOT="$HOME/my-knowledge-base"
3. Configure MCP for a project
From inside a project directory:
kb setup
Or specify the project name:
kb setup my-project
This auto-detects installed agents and:
- Creates MCP config in the project directory (
.mcp.jsonfor Claude Code,.codex/config.tomlfor Codex,opencode.jsonfor OpenCode) - Writes
@importpointers in CLAUDE.md (and AGENTS.md/AGENT.md if they exist) pointing to the KB context
Shows what will be written and asks for confirmation (-y to skip).
Restart your agent after setup to connect to the MCP server.
Claude Code expands this @import automatically β the full context loads as before. When Claude modifies the context, it edits the KB file (because of the directive header), not the repo's CLAUDE.md.
Browsing
Interactive TUI for navigating the knowledge base:
kb
- Launched outside a project β shows all projects and shared docs in dual-pane view
- Launched inside a registered project β jumps to that project's detail view
- Navigate with arrow keys or
h/l,tabto switch panes,/to filter, Enter to open, Esc to go back - Space to toggle ref/inline mode (project detail) or cycle global status (main view)
qorCtrl+Cto quit
Agent Usage
Agents use KB tools via MCP to search, read, and create docs on-demand.
Searching the knowledge base:

Reading shared API docs:

Creating a new shared doc:

Versioning
Every CLI write operation auto-commits to the KB's git repo with a descriptive message:
$ kb log
a1b2c3d 2026-03-04 02:26 ref: link my-project β rest-api-docs
e4f5a6b 2026-03-04 02:26 shared: add rest-api-docs (1 file(s), 500 lines)
c7d8e9f 2026-03-04 02:18 import: my-project from ~/repos/my-project/CLAUDE.md
0a6b0f2 2026-03-04 02:07 init: knowledge base
Auto-push
kb init offers to set up a git remote and enable auto-push. When enabled (auto_push: true in kb.yml), every commit is automatically pushed to the remote in the background.
MCP Server Tools
When configured, agents get 16 tools:
| Tool | Description |
|---|---|
kb_context | Read project context.md (equivalent to CLAUDE.md). Auto-detects project from cwd. |
kb_list | List project docs, linked shared docs, globals, and other available shared docs. |
kb_read | Read a specific doc by path. Supports offset/limit for large files. |
kb_search | Full-text search across KB. Scoped by project, shared docs, or all. |
kb_draft | Preview content before writing β returns formatted preview without persisting. |
kb_write | Create or update a file under shared/ or projects/. Auto-commits. |
kb_delete | Delete a shared doc (with cleanup of refs/globals) or a specific file. |
kb_log | Show version history. Scopeable to a project or shared doc. |
kb_diff | Show uncommitted changes in the knowledge base. |
kb_show | Read a file's content at a specific commit. |
kb_revert | Revert a file to a specific commit. Auto-commits the change. |
kb_ref_add | Link a shared doc to a project. Supports inline to embed content in context.md. |
kb_ref_remove | Unlink a shared doc from a project. |
kb_global_add | Mark a shared doc as globally available to all projects. Supports inline. |
kb_global_remove | Remove a shared doc from globals. |
kb_commit | Commit pending changes. Use after mutations with no_commit=true. |
The kb_draft β kb_write workflow ensures agents preview changes before persisting them.
Agents can create shared docs, link them, and manage globals entirely through MCP β no CLI needed.
Knowledge Base Structure
~/knowledge-base/
.git/ # Auto-managed version history
kb.yml # Config + project path mappings + globals
shared/ # Cross-project shared docs
rest-api-docs/
api-reference.md # The actual documentation
meta.yml # Optional: title, description, source, tags
design-patterns/
reactivity.md
projects/ # Per-project knowledge
my-project/
context.md # Project context (the "real" CLAUDE.md)
refs.yml # Links to shared docs: [rest-api-docs]
notes/ # Additional project-specific docs
architecture.md
Configuration files
kb.yml β Global config with project path mappings and globals:
version: 1
editor: hx # Fallback: $EDITOR, then vi
globals: # Shared docs available to all projects (referenced)
- style-guide
inline_globals: # Shared docs embedded into all projects' context.md
- coding-standards
projects:
my-project: ~/repos/my-project
other-project: ~/documents/other-project
work-api: /opt/work/api-server
Projects can be anywhere on disk β they don't need to be under a common directory.
refs.yml β Per-project shared doc references:
refs:
- rest-api-docs
- design-patterns
inline: # Embedded directly into context.md
- commit-conventions
meta.yml β Optional shared doc metadata:
title: REST API Reference
description: API endpoints, authentication, and usage examples
source: https://docs.example.com/api
tags: [api, rest, reference]
How CLAUDE.md integration works
Before kb
~/repos/my-project/CLAUDE.md β 300 lines of context, edited in-repo
~/repos/other-project/CLAUDE.md β Duplicate API docs, diverges over time
After kb
~/repos/my-project/CLAUDE.md β One line: @~/knowledge-base/projects/my-project/context.md
~/knowledge-base/
projects/my-project/context.md β The actual 300 lines, versioned, with edit directive
shared/rest-api-docs/ β API docs, shared by both projects
The repo's CLAUDE.md becomes a single @import pointer. Claude Code expands this at session start and sees the full content. The KB's context.md starts with:
<!-- KB managed: ~/knowledge-base/projects/my-project/context.md -->
<!-- Always edit THIS file for project context. Do NOT edit the repo's CLAUDE.md. -->
This directive ensures agents edit the KB file (versioned, centralized) rather than the repo's pointer file.
Context backup
When context.md is updated, kb copies it to .kb-context.md in the project directory. This keeps a versioned copy of the project context alongside your code.
Ref vs Inline
Shared docs can be linked in two modes:
- Ref (default) β listed in a
<!-- KB:REFS -->comment as a summary with line counts. Agents fetch content on-demand viakb_read/kb_search. Best for large reference docs. - Inline (
--inline) β content embedded directly intocontext.mdinside<!-- KB:INLINE -->blocks, loaded at session start. Best for small docs that should always be available (commit conventions, style guides).
CLI Commands
| Command | Description |
|---|---|
kb | Launch the TUI browser (default command) |
kb init [--dir PATH] | Initialize a new knowledge base |
kb setup [PROJECT] [-y] | Configure MCP + @import pointers for a project |
kb project init <NAME> --path <DIR> | Create a new project in the KB |
kb project import <NAME> --from <DIR> | Import existing CLAUDE.md/AGENTS.md into the KB |
kb project list | List all projects |
kb project show <NAME> | Show project details and context |
kb shared add <SLUG> <FILES...> | Add shared documents to the KB |
kb shared list | List shared documents with usage and line counts |
kb ref add <PROJECT> <SLUG> [--inline] | Link a shared doc to a project |
kb ref remove <PROJECT> <SLUG> | Unlink a shared doc from a project |
kb global add <SLUG> [--inline] | Make a shared doc available to all projects |
kb global remove <SLUG> | Remove a shared doc from globals |
kb global list | List global shared docs |
kb search <QUERY> [--project NAME] | Full-text search across the KB |
kb edit <PROJECT> | Open project context.md in $EDITOR |
kb detect | Auto-detect current project from working directory |
kb log [SCOPE] | Show version history |
kb diff [SCOPE] | Show uncommitted changes |
kb revert <REF> <PATH> | Revert a file to a previous version |
kb commit | Manually commit pending KB changes |
kb graph | Show ASCII reference graph of projects and shared docs |
kb version | Print version information |
kb mcp | Start MCP server (stdio transport) |
