Librarian

Librarian fetches and searches up-to-date developer docs on your machine.
Use it to give AI agents real context so they stop guessing and writing bad code.

Supports GitHub repos and public websites.

Install

npm

npm i -g @iannuttall/librarian

librarian setup

bun

bun add -g @iannuttall/librarian

librarian setup

Note: npm installs still require Bun at runtime; the CLI will prompt you to install it if missing.

Install Bun (optional):

curl -fsSL https://bun.sh/install | bash

Updates

Check your current version

librarian version

Update (auto-detects bun vs npm)

librarian update

Librarian also checks for updates once per day when you run any command and will suggest the right update command.

Quick start (from repo)

bun install

bun setup

If you choose the global install during setup, use librarian below.
Otherwise use ./librarian.

librarian add https://github.com/honojs/website --docs docs

librarian add https://hono.dev/docs

librarian ingest --embed

librarian library "honojs"

librarian search --library honojs/website "middleware"

Sources

GitHub repos

librarian add https://github.com/owner/repo --docs docs --ref main

librarian add https://github.com/owner/repo --version 16.x

Websites

Basic - auto-discovers via llms.txt, sitemap.xml, robots.txt

librarian add https://docs.example.com

With options

librarian add https://docs.example.com/api --depth 3 --pages 500

Specific paths

librarian add https://example.com --allow /docs,/api --deny /blog

Ingest

Ingest all sources

librarian ingest

Ingest with concurrency (default: 5)

librarian ingest --concurrency 10

Force re-ingest

librarian ingest --force

Ingest and embed

librarian ingest --embed

Seed sources

Add the built-in seed list and auto-ingest

librarian seed

The default seed list lives in data/libraries.yml in this repo.

Search

Hybrid search (word + meaning)

librarian search --library vercel/next.js "middleware"

Word search only

librarian search --library vercel/next.js --mode word "middleware"

Meaning search only

librarian search --library vercel/next.js --mode vector "middleware"

JSON output

librarian search --library vercel/next.js --json "middleware"

Filter by version

librarian search --library vercel/next.js --version 16.x "middleware"

To avoid mixed results, scope searches to a library version label. If you are in a repo, run:

librarian detect

Then pass the label to search. If you are not in a repo, run a library search first: librarian library "<name>" to see the available version labels.

Library search

Find a library and list versions

librarian library "nextjs"

Other commands

List sources

librarian source list

Remove source

librarian source remove 1

Add sources from the seed list

librarian seed

Read a doc

librarian get --library vercel/next.js docs/guide.md

Read a slice

librarian get --library vercel/next.js --doc 69 --slice 19:73

Show counts

librarian status

Detect versions in cwd

librarian detect

Update Librarian

librarian update

Remove inactive docs

librarian cleanup

MCP server

Start the MCP server (stdio)

librarian mcp

Tools:

• search (use mode for word/vector/hybrid)
• library
• get

Configuration

Config file: ~/.config/librarian/config.yml

github:
  token: ghp_xxx  # For private repos

proxy:
  endpoint: http://user:pass@proxy.example.com:8080
  # Any HTTP proxy works; tested with Webshare.

headless:
  enabled: true
  proxy: http://proxy.example.com:9999  # IP-whitelisted, no auth
  chromePath: /path/to/chrome  # Optional, auto-detected

crawl:
  concurrency: 5

ingest:
  maxMajorVersions: 3

Notes

• setup downloads the local embedding model
• Public repos don't need a GitHub token
• Website crawling auto-detects CSR/SPA sites and uses headless Chrome
• Chrome is auto-detected but can be configured manually
• Run librarian setup to check Chrome availability
• If librarian does not work in a repo checkout, use ./librarian
• More examples in docs/usage.md

Agent skills

Skills use progressive disclosure, so only the skill name and description load at startup.

Codex

• Copy the bundled skill to your Codex skills folder:

mkdir -p ~/.codex/skills

cp -R skills/librarian ~/.codex/skills/librarian

• Direct invocation works in Codex CLI: use $librarian or /skills
• Codex web and iOS do not support direct invocation yet, so just ask to use the librarian skill

Claude Code

• Copy the skill to your Claude Code skills folder:

mkdir -p ~/.claude/skills

cp -R skills/librarian ~/.claude/skills/librarian

Factory

• Copy the skill to your Factory skills folder:

mkdir -p ~/.factory/skills

cp -R skills/librarian ~/.factory/skills/librarian