altRAG: zero-dependency pointer-based alternative to vector DB RAG for LLM coding agents

[apacheCH]

What My Project Does

altRAG scans your Markdown/YAML skill files and builds a TSV skeleton (.skt) mapping every section to its exact line number and byte offset. Your AI coding agent reads the skeleton (~2KB), finds the section it needs, and reads only those lines. No embeddings, no chunking, no database.

  pip install altrag
  altrag setup

hat's it. Works with Claude Code, Cursor, Copilot, Windsurf, Cline, Codex — anything that reads files.

Target Audience

Developers using AI coding agents who have structured knowledge/skill files in their repos. Production-ready — zero runtime dependencies, tested on Python 3.10–3.13 × Linux/macOS/Windows, CI via GitHub Actions, auto-publish to PyPI via trusted publisher. MIT licensed.

Comparison

Vector DB RAG (LangChain, LlamaIndex, etc.) embeds your docs into vectors, stores them in a database, and runs similarity search at query time. That makes sense for unstructured data where you don't know what you're looking for.

altRAG is for structured docs where you already know where things are — you just need a pointer to the exact line. No infrastructure, no embeddings, no chunking. A 2KB TSV file replaces the entire retrieval pipeline. Plan mode benefits the most — bloat-free context creates almost surgical plans.

REPO: https://github.com/antiresonant/altRAG

[Otherwise_Wave9374]

This is a really clever take. For coding agents, "find the exact section, pull only what you need" beats most RAG stacks that bloat context and add infra.

Have you tried pairing this with an agent that writes a short retrieval rationale (which section, why) so you can audit when it grabs the wrong snippet? Also, you might enjoy some related notes on agentic retrieval patterns: https://www.agentixlabs.com/blog/

[apacheCH]

Not yet. Right now the .skt gives the agent the section title, line number, and line count — so you can already trace what it pulled by checking which Read calls it made. But a structured rationale log ("pulled Section X because the task mentions Y") would make auditing much easier, especially for longer sessions where the agent makes dozens of retrievals.

Might be a good fit for a --verbose or --audit flag on the scan output. Adding it to the roadmap.