Your LLM reads the whole file. It doesn't have to.

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.

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. Here'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. The 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. The cost isn't just tokens. A context window stuffed with irrelevant content makes the agent's answers worse. When 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. Markdown documents have a built-in structure: headings. A Title followed by Section A followed by Subsection A.1 creates a hierarchy that mirrors a book's table of contents. Split 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. This is the idea behind md2idx https://github.com/oubakiou/md2idx , a CLI tool. md2idx converts a Markdown file into JSON with two fields: index < markers for depth <serial . <heading text sections bash $ npx md2idx spec.md | jq -r '.index' 0. API Specification 1. Authentication 2. Endpoints 3. GET /users 4. POST /users 5. Error Handling 6. Rate Limiting The serial numbers match the array indices. To read the Error Handling section: bash $ npx md2idx spec.md | jq -r '.sections 5 ' Error Handling When a request fails, the API returns a JSON error object with... just the content of that one section To read a heading and all its children together: bash $ npx md2idx spec.md | jq -r '.sections 2:5 ' Endpoints, GET /users, and POST /users — all 3 sections For 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%. The output is designed to work with jq . One-line JSON by default pipe-friendly , --pretty for formatted output. Reads from a file argument or stdin. grep -nE ' {1,6} ' spec.md gives you a list of headings. For simple cases, that works. But md2idx covers problems that grep can't solve: jq '.sections N ' is all it takes === / --- : invisible to grep's pattern inside code fences link url etc. as-is. md2idx strips markup in the index while preserving it in section contentWith the md2idx-read skill, the agent autonomously handles everything from fetching the index to selecting sections. jq slicing install the skill gh skill install oubakiou/md2idx md2idx-read --agent claude-code --scope project or with npx npx skills add oubakiou/md2idx --skill md2idx-read --agent claude-code --yes Once 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. A fallback is included. If md2idx isn't available network-restricted environments, permission issues , it falls back to grep for headings and Read tool with offset/limit. Less accurate, but functional. read the index of any Markdown file npx md2idx README.md | jq -r '.index' grab a specific section by number npx md2idx README.md | jq -r '.sections 2 ' search within a section npx md2idx data.md | jq -r '.sections 4 ' | grep Tokyo global install npm install -g md2idx md2idx has zero external dependencies — a self-contained line scanner, not a Markdown AST parser. It handles ATX headings style , setext headings === / --- underlines , code fence skipping, and inline markup stripping. md2idx is MIT-licensed and fully open source. If your LLM agents are reading entire large Markdown files, give it a try: npx md2idx your-file.md | jq -r '.index' gh skill install oubakiou/md2idx md2idx-read If 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 .