NIA Docs - Docs as Filesystem for Agents
Turn any documentation site into a directory you can
cdinto. One command, zero install, zero auth. Agents use Unix primitives they already know (tree,grep,cat,find) instead of MCP tools or RAG.
The Thesis
Code hallucinations are not a model problem - they're a data problem. APIs ship breaking changes, deprecate endpoints, rename parameters. Models can't keep up because training data is months behind. The standard fix is RAG: chunk docs, embed them, retrieve top-K fragments. This gets 80% of the way until the answer spans multiple pages or requires exact function signatures that didn't survive chunking.
nia-docs takes a different approach: what if an agent could just read the docs? Not retrieve chunks, but browse them. The same way you'd grep through a codebase or cat a README.
Why Filesystem over MCP/RAG
Unix figured this out fifty years ago. Devices, processes, sockets - all files. One interface: open, read, write, close. Agents were pre-trained on Unix - billions of tokens of filesystem interactions baked into weights. tree, grep, find aren't tools agents learn to use; they're tools agents already know.
Compare to MCP: every tool needs a JSON schema, a natural-language description, and careful argument construction. Each one eats context window space. A filesystem needs none of that. Cloudflare's Code Mode analysis showed an equivalent MCP server without Code Mode would consume 1.17 million tokens - more than the entire context window of the most advanced models. The 2026 "Code Mode" approach (2 tools, fixed ~1K tokens, access to an entire API) validates the filesystem-first thesis.
The reviewed Anakin row is text-only, but it clarifies the comparison: the failure mode is not "MCP bad" in the abstract; it is high tool-schema/context overhead when an API is represented as many individually described tools. Code Mode-style access wins when it keeps the tool surface fixed and lets the agent inspect files or docs on demand.
As Jerry Liu (@jerryjliu0) put it: an agent with filesystem tools and a code interpreter is just as general, if not more general, than an agent with 100+ MCP tools.
BM25 and Hybrid Search
The RAG approach (embed + vector search + retrieve top-K) has a known weakness: exact keyword matching. If a user searches for "error code 5012," embeddings return semantically similar results; BM25 finds the exact match. BM25 - a 30-year-old algorithm with zero training, zero embeddings - still powers Elasticsearch, OpenSearch, and most production search systems. It asks three questions: how rare is this word (IDF), how many times does it appear (term frequency with saturation), and is this document unusually long (length normalization). The reviewed @akshay_pachaar image makes the formula legible: relevance is a weighted combination of inverse document frequency, saturated term frequency, and document-length normalization. Source: X/@akshay_pachaar, 2026-04-05; Source: local image artifact, 2026-07-03
The best production systems use hybrid search: BM25 for precision + vector search for semantic understanding + reranking for final ordering. The reviewed Elasticsearch artifact is a Query DSL retriever tree, not ES|QL; the author corrected the thread to "DSL not ESQL." It shows rrf fusion over standard lexical search and semantic retrieval, then text_similarity_reranker as the final ordering step. Elastic's current docs match that shape: the RRF retriever combines child retrievers such as standard keyword, kNN, sparse-vector, or weighted hybrid retrievers, while semantic reranking runs on a small top-k candidate set and can be invoked through text_similarity_reranker or ES|QL RERANK. Source: X/@helloiamleonie, 2026-04-02; Source: local artifact review, 2026-07-03; Source: Elastic RRF and semantic reranking docs, 2026-07-03
nia-docs takes a different approach entirely: skip search, mount the docs as a filesystem, and let the agent grep directly. For documentation (structured, relatively small, public), this is faster and more complete than either RAG or hybrid search.
Usage
# Browse docs interactively
npx nia-docs https://docs.stripe.com
# Run a single command and exit
npx nia-docs https://docs.stripe.com -c "grep -rl 'webhook' ."
npx nia-docs https://docs.stripe.com -c "cat getting-started.md"
# Set up for an agent
npx nia-docs setup https://docs.stripe.com | claude
npx nia-docs agents https://docs.stripe.com >> AGENTS.md
npx nia-docs agents https://docs.stripe.com >> CLAUDE.md
Works with Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode.
How It Works
Index: Crawls the site, respects llms.txt, detects OpenAPI specs, handles redirects. Each page becomes a file. URL docs.stripe.com/api/charges/create becomes /api/charges/create.md. Auto-detects common path prefix and strips it.
Serve: Filesystem operations as API endpoints: read, grep, ls, tree, find. Everything gzip-compressed. One round trip to boot. Responses cached (5 min server, disk cache at ~/.cache/nia-docs/). Namespaces are shared - when someone indexes a site, it's available to everyone.
Shell: Runs entirely on the client as an in-process TypeScript bash interpreter (via just-bash). No container, no sandbox, no VM. All files loaded into an in-memory JavaScript object. grep -r "webhook" . over 500 pages completes in milliseconds.
Performance
- Boot: ~100ms (cached), ~2s (already indexed), ~30-120s (cold index)
- Per-session compute: zero on server (files from Postgres, commands on client)
- No orchestration or warm pools needed
Agent Workflow Pattern
Agents converge on a consistent workflow when given filesystem access:
treeto orientgrep -rlto find relevant filescatto read them
This is exactly what a human developer would do. The filesystem abstraction isn't something agents learn - it's what they default to.
Integration with Wiki
Add to AGENTS.md or CLAUDE.md for any project that depends on external docs:
## Stripe Docs
Before working on a Stripe feature, check the docs:
npx nia-docs https://docs.stripe.com -c "grep -rl 'webhook' ."
npx nia-docs https://docs.stripe.com -c "cat getting-started.md"
The agent picks it up naturally. When it needs to check how something works, it runs the command, gets the actual current documentation, and writes code against that - not against whatever was in training data.
Sibling product — Vault
Same company (Nia / trynia.ai, Nozomio Labs). Where nia-docs mounts external docs as a filesystem, Nia Vault builds an agent-maintained personal wiki over your own indexed sources (the Karpathy LLM-wiki pattern, productized with a dream self-improvement loop). Source: Nia docs, https://docs.trynia.ai/vault, 2026-06-12
Timeline
- 2026-07-04 | Reviewed Anakin's Code Mode/MCP comparison row and attached it to this filesystem-over-MCP thesis. No new tool page was needed; the durable point is that fixed two-tool access avoids schema/context blowup for large APIs. Source: X/@anakin, 2026-04-04
- 2026-07-04 | Cleared the artifact-audit source-review row for the original @arlanr X Article bookmark. The anonymous enriched fetch remains an X login shell, but prior Playwright recovery already tied the source to this dedicated nia-docs page, so no new content page was needed beyond recording the raw enriched source. Source: raw/x-bookmarks/enriched/2041215978957389908.json; X/@arlanr, 2026-04-06
- 2026-07-03 | Deep-reviewed the hybrid-search screenshot and corrected the page from "ES|QL multi-stage retrievers" to Elasticsearch Query DSL retriever trees with RRF plus semantic reranking. Source: X/@helloiamleonie, 2026-04-02; Source: Elastic docs, 2026-07-03
- 2026-07-03 | Deep-reviewed the @akshay_pachaar BM25 formula image and tied the bookmark to the retrieval invariant: lexical search remains the precision layer for exact terms, IDs, commands, and error codes. Source: raw/x-bookmarks/enriched/2040776999728509414.json; local image artifact
- 2026-06-17 | Added timeline and made the Vault docs source explicit in frontmatter. Source: https://docs.trynia.ai/vault
- 2026-04-07 | Created nia-docs page from the launch bookmark and filesystem-over-RAG thesis. Source: https://x.com/arlanr/status/2041215978957389908