librarian: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Librarian — semantic documentation search for projects, powered by SQLite + sqlite-vec, exposed via MCP. Written in Go.

Build & Test

go build -o librarian .          # build binary
go test ./...                    # run all tests
go test ./internal/indexer       # run tests for a specific package
go test -v -run TestEmphasis     # run a specific test by name
make build                       # same as go build via Makefile

CGo is required (CGO_ENABLED=1, the Go default) because both mattn/go-sqlite3 and sqlite-vec are C libraries.

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts. Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms:

cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

• scp — use -o BatchMode=yes
• ssh — use -o BatchMode=yes to fail instead of prompting
• apt-get — use -y
• brew — use HOMEBREW_NO_AUTO_UPDATE=1

Librarian MCP

This project has a librarian MCP server configured in .mcp.json. Use it to understand the codebase — it is the default codebase-exploration surface in this repo.

• search_docs — semantic search across indexed docs (start here for most questions)
• get_context — deep briefing with related code files and documents (use for architecture/design questions)
• get_document — read a full doc by file path
• list_documents — browse all indexed docs
• update_docs — write/overwrite a doc and re-index it

Prefer these tools over Grep and over reading full files. Order to try: