Citepath

Status: pre-release (0.1). Expect breaking changes before 1.0.

What it does

• 📚 Indexes your docs: documentation websites (from the sitemap or by following links, respecting robots.txt) and local Markdown, MDX, or text folders.
• 🔗 Returns cited passages: each search result links to the exact page section or file lines it came from.
• 🧠 Understands code and plain English: getUserName, --dry-run, and "how do I configure caching" all work.
• 🤖 Connects to AI assistants: Claude Code, Cursor, and other MCP clients search your docs; your own tools use the CLI or a local HTTP API.
• 🔒 Runs locally: no account, no API keys, no telemetry. Assistants get read-only access, and a failed sync never deletes good data.

Citepath finds passages; it doesn't write answers. Your assistant writes the answer from those passages and cites them, so you can check every claim.

Demo

Index the current Next.js docs once, then search them:

citepath add nextjs --url https://nextjs.org/docs/app --include '/docs/app/**' --sync

[Searching the Next.js docs with citepath]

The same search works inside your assistant:

You: Using citepath, how do I set how long cached data lives in Next.js?

Claude: Add 'use cache' to the function and call cacheLife('hours'), or pass { stale, revalidate, expire }. This requires cacheComponents: true in next.config.ts. Sources: cacheLife, use cache, cacheComponents

Who it's for

• Developers using AI coding assistants: answers based on the current docs of your frameworks and services, not on what the model remembers.
• Builders of AI tools: a retrieval layer that returns ranked, cited passages as JSON for any model.
• Small teams: internal wikis, runbooks, and docs folders searchable by assistants, without a hosted platform.
• Open-source maintainers: an easy way for users to connect your project's docs to their assistants.

Why not RAG or web search?

It is RAG: the retrieval half, run locally. Instead of embeddings and a vector database, Citepath uses a keyword index. That means no embedding API or keys, exact matches on identifiers like cacheLife, the same results for the same query, and citations down to the section. The trade-off: it matches words, not meaning, so "sign in" won't find a page that only says "authentication".

Web search is better for broad, one-off questions. Citepath is better when:

• the docs are private: internal wikis, runbooks, and repo docs aren't on the web;
• the version matters: you choose what's indexed, and search prefers the current copy of a page over old versions;
• you want less to read: on the Next.js docs, 5 cited passages for "how do I set the cache lifetime" are about 4,200 characters, while the five pages they come from hold about 51,000 characters of text (the cacheLife page alone is about 1 MB of HTML);
• you're offline, or your assistant has no web search.

"The model already knows the docs." Only the version it was trained on. Fast-moving APIs, such as Next.js cacheLife, cacheComponents, or the new two-argument revalidateTag, are where models answer from outdated memory.

"Why not paste the docs into the prompt?" That works for a few pages. The Next.js docs are 845 pages; search picks the few passages that matter.

Costs and limits. Measured on a laptop with the Next.js and Vercel docs:

• Free to run: no account, API keys, or per-search fees. Searches take milliseconds (p95 13 ms across about 30,000 passages).
• Setup time and disk: syncing 845 Next.js pages took about 7.5 minutes at the polite default of 2 requests per second; the two sites use 83 MB.
• Freshness: results are as current as your last sync. There is no built-in scheduler, so run citepath sync from cron.
• Not indexed: sites that need JavaScript to render, PDFs, and docs behind a login.
• Single user: one API token, no per-user permissions.

Use something else for broad questions (web search), meaning-based search (embeddings), or team access control. See Known limitations.

Quick start

Requires Node.js 22.16 or later.

npm install -g citepath
citepath add my-docs --path ~/work/project/docs --synccitepath search "how do I configure authentication"
# Connect Claude Code (all projects)claude mcp add citepath -s user -- citepath mcp

Run /mcp in Claude Code to check the connection. For other assistants and scope options, see MCP setup. To run from source, see CONTRIBUTING.md.

Commands

Global options: --json, --quiet, --config <file>, --data-dir <dir>. See the CLI reference for all options.

Documentation

CLI · Configuration · How sync works · MCP setup · Local API · Result contract · Evaluation · Limitations · Design

Contributing

Contributions are welcome. Read CONTRIBUTING.md, open an issue before a larger feature, and report security problems privately as described in SECURITY.md.

License

MIT