agents-docs

Ultra-fast, zero-bloat local markdown documentation RAG for AI coding agents via MCP.
Instant BM25 search over official framework documentation and live AI model registries. Shared across Cursor, Claude Code, Antigravity, and Zed.

Why .agents/docs?

Coding agents frequently hallucinate deprecated APIs (Svelte 4 vs 5 Runes, Tailwind v3 vs v4, React 19 Actions) or reference outdated LLM models and token pricing.

Traditional vector-embedding RAG solutions are bloated: they require Docker containers, hundreds of megabytes of Python dependencies (Chroma, LangChain), and slow API embedding calls that split code blocks in half.

agents-docs applies the Lolaplex philosophy:

• Zero Vector DBs: Header-aware markdown chunking + pure Python lexical BM25 ranking with header match boost (+6.0) and full phrase boost (+10.0).
• Sub-10ms Search: Instant retrieval directly from plain markdown files on disk (~/.agents/docs/).
• Live AI Models Registry: Real-time tracked context windows, benchmarks, and token pricing ($/1M) for Frontier and Open-Weights models (Claude 5/4, GPT-5/o3/o4, Gemini 3.x, DeepSeek V4/R1, Qwen 2.5 Coder).
• Curated 21+ Framework Catalog: 1-click sync for official llms.txt (TypeScript Handbook, Svelte 5, FastAPI, Tailwind v3/v4, Tauri 2, Next.js, Supabase, Hono, WXT, Netlify, Coolify, Cloudflare, Resend, React, Vite, Zod, Pydantic, shadcn/ui).
• Deterministic Noise Pruning: Automatically strips HTML wrappers, link noise, and cookie banners without altering code blocks or tables.
• Universal MCP Server: FastMCP stdio interface with auto-sync and dependency manifest inspection.

Architecture & Flow

 ┌─────────────────────────────────────────────────────────────┐
 │                  DOCS & MODEL REGISTRIES                    │
 │    Official llms.txt · TypeScript Handbook · OpenRouter     │
 └──────────────────────────────┬──────────────────────────────┘
                                │  agents-docs sync <name>
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                 DETERMINISTIC NOISE PRUNER                  │
 │    Strips HTML boilerplate while preserving 100% of code    │
 └──────────────────────────────┬──────────────────────────────┘
                                │  Header-aware chunking
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                   LOCAL DOCUMENTATION STORE                 │
 │   ~/.agents/docs/ai-models/       ~/.agents/docs/svelte-5/  │
 │   ~/.agents/docs/typescript/      ~/.agents/docs/fastapi/   │
 └──────────────┬───────────────────────────────┬──────────────┘
                │                               │
                ▼                               ▼
 ┌─────────────────────────────┐ ┌─────────────────────────────┐
 │        LEXICAL BM25         │ │     MCP SERVER & CLERK      │
 │  Header Match Boost (+6.0)  │ │  search_docs · list_docsets │
 │  Sub-10ms Exact Retrieval   │ │  sync_project_docs          │
 └─────────────────────────────┘ └─────────────────────────────┘

Quickstart

1-Step Setup

pip install agents-docs && agents-docs init

Scaffolds ~/.agents/docs/, seeds the live ai-models registry, autowires MCP configurations into your installed IDEs, and registers assistant skills.

[!TIP] 🤖 Agent-Driven Setup (Zero Friction):
Simply tell your coding agent: "Install and set up agents-docs for me."
The agent installs the package, runs agents-docs init, and automatically retrieves fresh documentation whenever you ask technical stack or model pricing questions.

CLI Reference

MCP Tools Reference

Supported Ecosystem

• Claude Code: Bound via MCP server and .agents/skills/docs-search.
• Google Antigravity: Integrated via .gemini/config rules and agents-docs MCP.
• Cursor: Automatically configures .cursor/mcp.json and agent rules.
• Zed: Configures context_servers and mirrors assistant skills.
• VS Code / Windsurf: Autowires Cline / Roo-Code MCP configuration.

Open ABI Specification

Detailed architectural specifications live in abi/:

• abi/WHY.md — Architectural rationale & BM25 vs Vector embeddings.
• abi/LAYOUT.md — Storage taxonomy in ~/.agents/docs/.
• abi/MCP.md — Tool surface definitions and schemas.
• abi/CATALOG.md — Curated catalog schema and supported types.
• abi/LLMSTXT.md — Support for the llms.txt standard.

Testing & Verification

Run the test suite across all engines:

python tests/run_all_tests.py

License

MIT License. See LICENSE for details.