{"slug": "your-llm-reads-the-whole-file-it-doesn-t-have-to", "title": "Your LLM reads the whole file. It doesn't have to.", "summary": "A developer created md2idx, a CLI tool that splits Markdown files at heading boundaries into a JSON index and sections, enabling LLM coding agents to read only relevant parts instead of entire files. This reduces token consumption by 80-98% and improves answer quality by avoiding context window bloat. The tool is available on GitHub and includes a skill for autonomous agent use.", "body_md": "Coding agents read specs, design docs, and long READMEs every day. Most of the time, they only need a few sections. Yet they load the entire file into context.\n\nHere's a scenario that plays out constantly. You ask your agent to check the error handling section of a 5,000-line API spec. The agent opens the file, reads all 5,000 lines into its context window, finds the 80 lines it needs, and answers your question.\n\nThe result is correct. But the agent also consumed a large number of tokens on the 4,920 lines it didn't need. Repeat this for every file read in a session, and the waste compounds fast.\n\nThe cost isn't just tokens. A context window stuffed with irrelevant content makes the agent's answers worse.\n\nWhen a human picks up a 300-page technical book, they don't read cover to cover to find the chapter on authentication. They flip to the table of contents, scan the chapter titles, and jump to page 47. LLMs can do the same thing.\n\nMarkdown documents have a built-in structure: headings. A `# Title`\n\nfollowed by `## Section A`\n\nfollowed by `### Subsection A.1`\n\ncreates a hierarchy that mirrors a book's table of contents.\n\nSplit a Markdown file at heading boundaries, and you get a natural \"table of contents + sections\" structure. Each heading starts a new section, the heading text becomes the index entry, and the section number becomes the address.\n\nThis is the idea behind [md2idx](https://github.com/oubakiou/md2idx), a CLI tool.\n\nmd2idx converts a Markdown file into JSON with two fields:\n\n`index`\n\n`<# markers for depth> <serial>. <heading text>`\n\n`sections`\n\n``` bash\n$ npx md2idx spec.md | jq -r '.index'\n# 0. API Specification\n## 1. Authentication\n## 2. Endpoints\n### 3. GET /users\n### 4. POST /users\n## 5. Error Handling\n## 6. Rate Limiting\n```\n\nThe serial numbers match the array indices. To read the Error Handling section:\n\n``` bash\n$ npx md2idx spec.md | jq -r '.sections[5]'\n## Error Handling\n\nWhen a request fails, the API returns a JSON error object with...\n(just the content of that one section)\n```\n\nTo read a heading and all its children together:\n\n``` bash\n$ npx md2idx spec.md | jq -r '.sections[2:5][]'\n# Endpoints, GET /users, and POST /users — all 3 sections\n```\n\nFor a 5,000-line spec where the agent needs 2 sections, context usage goes from ~5,000 lines to ~100 lines (20-line index + 80 lines of content). Depending on the document and which sections are needed, the reduction is typically 80–98%.\n\nThe output is designed to work with `jq`\n\n. One-line JSON by default (pipe-friendly), `--pretty`\n\nfor formatted output. Reads from a file argument or stdin.\n\n`grep -nE '#{1,6} ' spec.md`\n\ngives you a list of headings. For simple cases, that works. But md2idx covers problems that grep can't solve:\n\n`jq '.sections[N]'`\n\nis all it takes`===`\n\n/ `---`\n\n): invisible to grep's `#`\n\npattern`#`\n\ninside code fences`[link](url)`\n\netc. as-is. md2idx strips markup in the index while preserving it in section contentWith the `md2idx-read`\n\nskill, the agent autonomously handles everything from fetching the index to selecting sections.\n\n`jq`\n\nslicing\n\n```\n# install the skill\ngh skill install oubakiou/md2idx md2idx-read --agent claude-code --scope project\n\n# or with npx\nnpx skills add oubakiou/md2idx --skill md2idx-read --agent claude-code --yes\n```\n\nOnce installed, the agent uses the skill proactively whenever it encounters a large Markdown file. No manual invocation needed — it reads the index first, picks sections, and skips the rest.\n\nA fallback is included. If md2idx isn't available (network-restricted environments, permission issues), it falls back to `grep`\n\nfor headings and Read tool with offset/limit. Less accurate, but functional.\n\n```\n# read the index of any Markdown file\nnpx md2idx README.md | jq -r '.index'\n\n# grab a specific section by number\nnpx md2idx README.md | jq -r '.sections[2]'\n\n# search within a section\nnpx md2idx data.md | jq -r '.sections[4]' | grep Tokyo\n\n# global install\nnpm install -g md2idx\n```\n\nmd2idx has zero external dependencies — a self-contained line scanner, not a Markdown AST parser. It handles ATX headings (`#`\n\nstyle), setext headings (`===`\n\n/ `---`\n\nunderlines), code fence skipping, and inline markup stripping.\n\n**md2idx** is MIT-licensed and fully open source. If your LLM agents are reading entire large Markdown files, give it a try:\n\n`npx md2idx your-file.md | jq -r '.index'`\n\n`gh skill install oubakiou/md2idx md2idx-read`\n\nIf you've tried it in your agent workflow, I'd love to hear how it went — drop a comment below or [open an issue on GitHub](https://github.com/oubakiou/md2idx/issues).", "url": "https://wpnews.pro/news/your-llm-reads-the-whole-file-it-doesn-t-have-to", "canonical_source": "https://dev.to/kiou_ouba_afbd120335456f3/your-llm-reads-the-whole-file-it-doesnt-have-to-hem", "published_at": "2026-06-19 12:05:00+00:00", "updated_at": "2026-06-19 12:07:10.993876+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents"], "entities": ["md2idx", "GitHub", "jq", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/your-llm-reads-the-whole-file-it-doesn-t-have-to", "markdown": "https://wpnews.pro/news/your-llm-reads-the-whole-file-it-doesn-t-have-to.md", "text": "https://wpnews.pro/news/your-llm-reads-the-whole-file-it-doesn-t-have-to.txt", "jsonld": "https://wpnews.pro/news/your-llm-reads-the-whole-file-it-doesn-t-have-to.jsonld"}}