booklib

<p align="center"> <img src="assets/logo.svg" width="140" alt="booklib"/> </p>

<h1 align="center">booklib</h1>

<p align="center"> A context engineering tool for AI coding assistants.<br/> Detects post-training knowledge gaps, resolves them automatically,<br/> and delivers your team's decisions via MCP to Claude, Cursor, Copilot, and 10+ tools. </p>

<p align="center"> <a href="https://www.npmjs.com/package/@booklib/core"><img src="https://img.shields.io/npm/v/@booklib/core.svg" alt="npm version"/></a> <a href="https://www.npmjs.com/package/@booklib/core"><img src="https://img.shields.io/npm/dw/@booklib/core.svg" alt="downloads"/></a> <a href="https://github.com/booklib-ai/booklib/stargazers"><img src="https://img.shields.io/github/stars/booklib-ai/booklib?style=flat" alt="stars"/></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="license"/></a> <a href="https://github.com/booklib-ai/booklib/actions"><img src="https://img.shields.io/github/actions/workflow/status/booklib-ai/booklib/check.yml?branch=main" alt="CI"/></a> </p>

<p align="center"> 767 tests  ·  23 expert skills  ·  10 ecosystems  ·  11 languages  ·  14 AI tools </p>

---

The Problem

Your AI writes code using knowledge from its training data. Your project uses libraries released after that cutoff. The result: hallucinated APIs, deprecated patterns, and code that doesn't compile.

Your team's decisions — use PaymentIntents, not Charges; always wrap API responses; never useEffect for data fetching — exist nowhere in the AI's training data. The code it generates is idiomatic React or idiomatic Node — just not idiomatic yours.

When we asked Claude to write code for botid (published 2026-03-03, post-training):

"I can't verify the botid package's actual API. I won't output code for a package whose API I can't verify. Guessing function names and signatures would likely give you broken code."

The Fix

BookLib detects every post-training API in your codebase and resolves the gaps automatically.

<p align="center"> <img src="assets/demo.gif" width="800" alt="booklib analyze on vercel/ai-chatbot — 274 post-training APIs detected"/> </p>

_{Real output: <code>booklib analyze</code> on <a href="https://github.com/vercel/ai-chatbot">vercel/ai-chatbot</a> — 82 dependencies, 274 post-training APIs across 158 files.}

Without BookLib — AI uses AI SDK v5 patterns from training data:

import { OpenAIStream, StreamingTextResponse } from 'ai';  // removed in v6
import OpenAI from 'openai';

export async function POST(req: Request) {
  const response = await new OpenAI().chat.completions.create({
    model: 'gpt-4', stream: true, messages,
  });
  return new StreamingTextResponse(OpenAIStream(response));
}

With BookLib — AI gets v6 docs injected at runtime:

import { streamText, convertToModelMessages,
  createUIMessageStreamResponse } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const result = streamText({
    model: openai('gpt-4o'),
    messages: convertToModelMessages(messages),
  });
  return createUIMessageStreamResponse({
    stream: result.toUIMessageStream(),
  });
}

---

Getting Started

Requires Node.js >= 18.

npm install -g @booklib/core
booklib init

The wizard detects your stack, configures MCP for your AI tools, and builds the knowledge index. Then see what your AI doesn't know:

booklib analyze

Website and skill browser at booklib-ai.github.io/booklib.

---

How It Works

Most context tools wait for your AI to ask. BookLib detects gaps before coding starts and injects corrections as code is written.

1. Detect Knowledge Gaps

Scans your dependencies across npm, PyPI, Maven, Crates.io, RubyGems, Go modules, Packagist, Pub, Swift, and NuGet. Checks publish dates against the model's training cutoff, then cross-references with your source code to find the exact files and APIs affected.

2. Resolve Automatically

For each gap, BookLib fetches current documentation:

1. Context7 — instant, version-specific library docs
2. GitHub — releases, wiki, and discussions
3. Manual — suggests the right booklib connect command

3. Protect at Runtime

PreToolUse and PostToolUse hooks inject context as your AI writes code:

• Runtime injection — 3-10 lines of relevant knowledge inserted before each edit, powered by a pre-computed context map
• Import checking — flags unknown APIs not in the index (11 languages)
• Contradiction detection — warns when code violates team decisions in real-time

4. Capture Team Knowledge

Your team's decisions live nowhere in public docs. BookLib auto-detects project documentation — specs, ADRs, architecture docs — and indexes them alongside your team decisions.

booklib capture --title "use PaymentIntents not Charges" --type decision
booklib connect notion database <db-id>
booklib connect github discussions org/repo

---

Features

Feature	Details
Gap Detection	10 package ecosystems, cross-referenced with source code
Runtime Injection	Pre/PostToolUse hooks deliver context as AI writes code
Context Map	Maps knowledge to code scopes via imports, terms, file patterns
Auto-Resolution	Context7 + GitHub + web connectors fetch current docs
Processing Modes	Fast (BM25), Local (Ollama), Cloud AI — choose in wizard
Import Checking	Flags unknown APIs in JS/TS, Python, Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift, Dart
Decision Checking	Detects when code contradicts captured team rules
Knowledge Graph	Nodes, typed edges, auto-linking, BFS traversal
Source Connectors	GitHub, Notion, Context7, local files, web docs, SDD specs (.specify, .planning, .kiro)
Source Detection	Auto-detects 12 content types: OpenAPI, ADRs, Gherkin, project docs, and more
Hybrid Search	BM25 + vector search + Reciprocal Rank Fusion + cross-encoder reranking
23 Expert Skills	Distilled from Effective Java, Clean Code, DDD, and 20 more canonical books

---

Works With

booklib init detects your AI tools and configures MCP automatically.

<p align="center"> <a href="https://claude.ai/code">Claude Code</a> · <a href="https://cursor.com">Cursor</a> · <a href="https://github.com/features/copilot">Copilot</a> · <a href="https://github.com/google-gemini/gemini-cli">Gemini CLI</a> · <a href="https://openai.com/index/introducing-codex">Codex</a> · <a href="https://windsurf.com">Windsurf</a> · <a href="https://roocode.com">Roo Code</a> · <a href="https://block.github.io/goose">Goose</a> · <a href="https://zed.dev">Zed</a> · <a href="https://continue.dev">Continue</a> · <a href="https://docs.all-hands.dev">OpenHands</a> · <a href="https://www.jetbrains.com/junie">Junie</a> · <a href="https://github.com/opencode-ai/opencode">OpenCode</a> · <a href="https://github.com/cpacker/letta">Letta</a> </p>

10 tools via MCP, 14 total with instruction-file support. See AGENTS.md for per-tool setup.

---

CLI Reference

Setup

Command	Description
booklib init	Guided setup — detects stack, configures MCP, builds index
booklib index	Rebuild the search index
booklib doctor	Health check for skills and config

Daily use

Command	Description
booklib gaps	Find post-training dependencies
booklib resolve-gaps	Auto-fix gaps via Context7 and GitHub
booklib analyze	Show affected files and post-training APIs
booklib search "<query>"	Search skills and knowledge

Knowledge

Command	Description
booklib capture --title "<t>"	Save a team decision or insight
booklib check-imports <file>	Flag unknown APIs
booklib check-decisions <file>	Check code against team rules

Sources

Command	Description
booklib connect <path>	Index local documentation
booklib connect github releases <repo>	Index GitHub changelogs
booklib connect notion database <id>	Index Notion pages
booklib sources	List connected sources

Run booklib --help --all for the full list.

---

Architecture

Everything runs locally by default. Embeddings via HuggingFace Transformers (CoreML on macOS, CPU elsewhere), vector search via Vectra, lexical search via BM25, all persisted in .booklib/. Optional cloud modes (Ollama, Anthropic, OpenAI) for AI-powered reasoning.

BookLib complements code context tools:

Layer	Tool	What it knows
Documentation	Context7	Current library APIs
Code structure	lsp-mcp	Functions, types, call graphs
Knowledge	BookLib	Post-training gaps, team decisions, expert principles

---

Contributing

See CONTRIBUTING.md for the full guide.

MIT License | Issues | Ko-fi | Docs

<p align="center"> <a href="README.md">English</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.pt-BR.md">Português</a> · <a href="README.uk.md">Українська</a> </p>