English · 中文 · 日本語 · 한국어 · Português · Українська

booklib

Knowledge bookkeeping for AI agents — expert skills, hybrid search, MCP tools.
24 curated skills from canonical books, personal knowledge graph, and integration with 13 AI tools via MCP.
Works for programming, product, writing, strategy, design, and more.

24 bundled skills  ·  258+ discoverable  ·  13 agents  ·  10 MCP-compatible  ·  obra/superpowers & ruflo compatible

What it is

BookLib packages expert knowledge from canonical books into skills that AI agents can apply directly to your work. It ships with 24 curated skills — and a discovery engine that can find, index, and inject hundreds more from the community.

Two layers:

BookLib is not a static install. It's a local knowledge engine: semantic search over skill content, automatic context injection via hooks, role-based profiles for swarm agents, and a sync bridge that makes every fetched skill available to any Claude Code-compatible orchestrator.

Not just for code. BookLib works for any domain where expert knowledge matters. The community registry includes skills for product management, technical writing, brand design, market research, and business strategy — booklib context extracts relevant principles from all of them the same way it does for code.

Knowledge Graph. Beyond book skills, BookLib lets you build a personal knowledge graph from your actual work — research findings, architectural decisions, team notes — and link that knowledge to the components of your own project. When you edit a file, the graph injects not just book wisdom but your own captured context too.

How Skills Activate

The hook is the fine-grained layer. After booklib hooks install, it fires on every Read/Edit/Write/Bash call, matches the file path against skill patterns, and silently injects the relevant skill sections into context — no manual invocation needed. Edit a .kt file and effective-kotlin appears. Edit a .py file and effective-python appears.

The Skill tool is the coarse layer — a full knowledge dump for orchestrator subagents that need an entire skill domain up front.

Quick Start

# 1. Install
npm install -g booklib

# 2. Connect to your AI tool (writes CLAUDE.md, .cursor/rules/, copilot-instructions.md)
booklib init

# 3. Build the local search index
#    First run downloads a ~25 MB embedding model — takes about 1 minute.
booklib index

# 4. Install the PreToolUse hook — injects relevant skills when you edit files
booklib hooks install

# 5. Search for wisdom by concept
booklib search "how to handle null values in Kotlin"

Works with 13 AI tools. booklib init auto-detects Claude Code, Cursor, Copilot (VS Code), Gemini CLI, Codex, Windsurf, Roo Code, Goose, Zed, Continue, OpenHands, Junie, and Letta. For the 10 MCP-capable tools, it also configures the MCP server so your agent can call BookLib tools (search, audit, capture) directly mid-conversation.

Your First 5 Minutes with the Knowledge Graph

After the Quick Start, do this once to see BookLib's full power:

# 1. Define a component — maps source files to a named node in the graph
booklib component add auth "src/auth/**"

# 2. Capture a note about your architecture decision
echo "Use short-lived JWTs (15 min) with refresh token rotation" | booklib note "JWT strategy"

# 3. Link the note to the component
booklib link "JWT strategy" "auth" --type applies-to

# 4. Now ask for context — BookLib injects both book wisdom and your own captured knowledge
booklib context "implement JWT middleware" --file src/auth/middleware.js

You'll see a ## Knowledge Graph Context section in the output with your note alongside the relevant book principles. This is graph-aware context injection — it traverses the graph from the component owning the file, finds linked knowledge, and combines it with semantic search.

Bundled Skills

Discovery

BookLib can find and index skills beyond the bundled set. Configure sources in booklib.config.json:

{
  "sources": [
    { "type": "registry", "trusted": true },
    { "type": "manifest", "url": "./community/registry.json", "trusted": true },
    { "type": "github-skills-dir", "repo": "obra/superpowers", "dir": "skills", "branch": "main", "trusted": true },
    { "type": "github-skills-dir", "repo": "ruvnet/ruflo", "dir": ".claude/skills", "branch": "main", "trusted": true },
    { "type": "github-org", "org": "your-org" },
    { "type": "npm-scope", "scope": "@your-scope" }
  ]
}

booklib discover              # list available skills from all sources
booklib discover --refresh    # force re-scan (bypass 24h cache)
booklib fetch naming-cheatsheet    # download and index a specific skill
booklib setup                 # fetch all trusted skills at once

Source types: registry (bundled), manifest (JSON list at URL or local path), github-skills-dir (any repo with a skills/ subdirectory), github-org, npm-scope.

"trusted": true marks a source as auto-installable by booklib setup. Untrusted sources are discoverable but require explicit booklib fetch <name> with a confirmation prompt.

Set GITHUB_TOKEN to raise the GitHub API limit from 60 to 5000 req/hr:
GITHUB_TOKEN=$(gh auth token) booklib discover --refresh

Orchestrator Compatibility

After booklib sync, every fetched skill lives at ~/.claude/skills/<name>/SKILL.md — the path Claude Code's native Skill tool reads from. No extra configuration needed.

booklib sync    # write all fetched skills to ~/.claude/skills/

BookLib uses a .booklib marker file to track directories it manages and never overwrites skills you placed there manually.

Swarm & Role-Based Profiles

Equip agents in a swarm with the right skills for their role:

booklib profile reviewer     # skills for a code reviewer agent
booklib profile security     # skills for a security auditor
booklib profile architect    # skills for a system design agent

Roles: architect · coder · reviewer · tester · security · frontend · optimizer · devops · ai-engineer · manager · product · writer · strategist · designer · legal

Get a full skill map for a swarm trigger pipeline:

booklib swarm-config audit      # security → tester agent roles + their skills
booklib swarm-config feature    # architect → coder → reviewer → tester
booklib swarm-config            # list all configured triggers

Project Setup

Scaffold context files for every AI tool in the project from a single command:

booklib init                         # Phase 1: .cursor/rules, CLAUDE.md, copilot-instructions, .gemini/context.md
                                     # Phase 2: MCP server config for Claude Code, Cursor, Gemini, Codex, Zed, Continue
booklib init --orchestrator=obra     # also shows superpowers install instructions
booklib init --orchestrator=ruflo    # also shows ruflo install instructions
booklib init --mcp-tool=claude,zed   # non-interactive MCP setup for specific tools

booklib init runs in two phases: first it writes AI tool standards files, then it interactively offers to wire up the MCP server so your tools can call booklib search and context directly. Re-run after adding new skills — it updates all files in place without overwriting your existing configs.

Agents

Knowledge Graph

BookLib can capture knowledge from your actual work and link it to your project's own topology — forming a unified graph where book skills, research notes, and architectural decisions all live together.

Nodes

Every piece of knowledge is a plain Markdown file in .booklib/knowledge/nodes/ with YAML frontmatter. Node types: research · note · decision · fact · component · feature · skill.

# Capture a note (opens $EDITOR, or pipe content in)
booklib note "JWT refresh token patterns"
echo "Short expiry + rotation" | booklib note "JWT refresh token patterns"

# Type or dictate — AI structures it, fixes grammar, extracts title + tags
booklib dictate
booklib dictate --raw                  # verbatim, no AI processing
booklib dictate --title "auth idea"

# Save the current agent conversation as a knowledge node
booklib save-chat --title "Auth redesign decisions"
booklib save-chat --summarize          # AI extracts key decisions, attaches transcript

# Create a research stub (saves as a node for you to fill in)
booklib research "JWT refresh token patterns"

Project Components

Define which parts of your project map to which components. When you edit a file, BookLib finds the owning component and injects all knowledge attached to it:

booklib component add auth "src/auth/**"
booklib component add payments "src/payments/**" "src/billing/**"

Components are just component nodes in .booklib/knowledge/nodes/ — same format, no separate config file.

Edges

Connect nodes with typed relationships:

# Link by title — no need to look up IDs
booklib link "JWT strategy" "auth" --type applies-to
booklib link "auth" "payments" --type depends-on
booklib link "JWT strategy" "RFC 7519 notes" --type see-also

# Exact IDs still work if you prefer
booklib link node_abc123 comp_auth456 --type applies-to

Edge types: implements · contradicts · extends · applies-to · see-also · inspired-by · supersedes · depends-on

All edges live in .booklib/knowledge/graph.jsonl — append-only, git-trackable.

Inspect

booklib nodes list                     # list all nodes
booklib nodes show node_abc123         # view a specific node

Context Injection with Graph

booklib context automatically incorporates the knowledge graph alongside book skills when you pass a file path:

booklib context "implement jwt auth" --file src/auth/middleware.js

This finds the owning component (comp_auth), traverses its edges, runs semantic search, and injects the most relevant book wisdom + your own captured knowledge together.

Context Builder

booklib context is the most powerful way to use BookLib before starting a task. It searches across all indexed skills simultaneously, extracts the most relevant passage from each matched book, and surfaces every decision it makes — including the quiet ones:

booklib context "implement a payment service in Kotlin with async error handling"
booklib context "implement jwt auth" --file src/auth/middleware.js   # also injects graph context

Output:

• For each matched book: book title + section + specific passage that applies to your task
• Auto-resolved decisions (one book clearly more relevant): shown with prose rationale — non-blocking, you just see why
• Genuine conflicts (two books equally applicable): interactive [a/b] prompt with passage previews so you can make an informed choice
• A final sharp system-prompt block with all resolved knowledge stitched together, every piece cited with its source

Works for any domain, not just code:

booklib context "design a rate limiter for a distributed API"
booklib context "refactor a God class in Python" --prompt-only   # just the prompt, no report
booklib context "add streaming to a Next.js chat UI" --prompt-only | pbcopy
booklib context "write a compelling investor update email"
booklib context "design a landing page for a SaaS product"
booklib context "structure a product requirements document for checkout"

Semantic Search & Audit

booklib search "how to handle null values in Kotlin"
booklib search "event sourcing vs CQRS" --role=architect   # filter to skills tagged for that role
booklib audit effective-kotlin src/PaymentService.kt        # systematic review of a file
booklib scan            # wisdom heatmap — violations per skill across the whole project (code)
booklib scan --docs     # prose quality scan — passive voice, placeholders, hedge words in .md/.txt files

Session Handoff

Preserves full context when switching agents or hitting rate limits:

booklib save-state --goal="..." --next="..." --progress="..."
booklib resume
booklib recover-auto    # auto-recover from last session or git history

Multi-agent coordination:

booklib sessions-list
booklib sessions-merge auth-session,payment-session combined
booklib sessions-lineage main feature-x "branched for auth work"
booklib sessions-compare python-audit,kotlin-audit src/auth.ts comparison

All session data lives in .booklib/ (gitignored). Nothing sent to any server.

MCP Server

BookLib ships a local MCP server that gives any MCP-compatible AI agent access to both the skill library and the knowledge graph.

# Automatic setup (recommended) — run once, picks up all your tools:
booklib init

# Manual setup if needed:
# Claude Code
claude mcp add booklib -- booklib-mcp

# Cursor / Gemini / Codex / Zed / Continue — booklib init writes the right file for each

Available tools:

Agent compatibility:

Quality

Each bundled skill is evaluated by asking a model to review code with and without the skill active. Delta = pass rate with skill minus pass rate without — it measures how much the skill actually changes model behaviour. A delta of +0pp means the model already knew it; a high delta means the skill is genuinely teaching it something new.

Thresholds: pass rate ≥ 80% · delta ≥ 20pp · baseline < 70%

Run evals: ANTHROPIC_API_KEY=... npx booklib eval <name>

Repo Structure

booklib-ai/booklib/
├── skills/                   22 bundled skills (SKILL.md + examples + evals)
├── community/                community skill registry (registry.json)
├── agents/                   8 autonomous reviewer agents
├── commands/                 slash commands, one per skill
├── rules/                    always-on language standards
├── hooks/                    Claude Code hooks (PreToolUse + PostToolUse)
├── booklib.config.json       discovery source configuration
└── lib/
    ├── engine/               indexer, searcher, auditor, scanner, handoff, sessions
    │   ├── graph.js          knowledge graph: node CRUD, edge append, BFS traversal
    │   ├── capture.js        node creation: editor, stdin, AI structuring, dictation
    │   └── graph-injector.js injection pipeline: semantic + graph traversal combined
    ├── context-builder.js    cross-skill context builder (+ graph-aware buildWithGraph)
    ├── skill-fetcher.js      fetch skills from GitHub/npm, sync to ~/.claude/skills/
    ├── discovery-engine.js   scan configured sources for available skills
    ├── project-initializer.js generate context files for all AI tools
    └── ...
bin/
    ├── booklib.js            CLI (registered as `booklib`)
    └── booklib-mcp.js        MCP server

.booklib/ (gitignored) — local state: sessions/ for handoffs, index/ for search index, skills/ for fetched community skills, knowledge/ for graph nodes and edges.

Trust & Transparency

• Book-grounded — every bundled skill extracts practices from a canonical programming book
• Evaluated — quantitative evals: pass rate, delta over no-skill baseline
• Open discovery — community registry and source config are public and auditable
• Local-first — indexing, search, and session data stays on your machine
• Marker-based ownership — .booklib marker tracks which ~/.claude/skills/ dirs BookLib manages; never overwrites yours
• Five runtime deps — @xenova/transformers, vectra, gray-matter, @modelcontextprotocol/sdk, minimatch

Contributing

To add a bundled skill:

cp -r skills/clean-code-reviewer skills/your-book-name
# Edit SKILL.md, examples/before.md, examples/after.md, evals/evals.json
npx booklib check your-book-name

To add a community skill, edit community/registry.json and open a PR.
To add an external source, edit booklib.config.json.

See CONTRIBUTING.md for the full guide.

Open requests: The Pragmatic Programmer · Clean Architecture · A Philosophy of Software Design · more →

History

Full commit history at github.com/booklib-ai/booklib.

Feedback & Issues

Found a bug? Have a suggestion? Open an issue — all feedback welcome.

Star

If BookLib has helped you write better code, a ⭐ on GitHub helps me know people are using it — and helps others discover it.

Supporters

Thanks to everyone who supports BookLib on Ko-fi ☕

Be the first — your name here.

License

MIT