You write docs for humans, then an AI agent reads them every day and pays tokens for every star, every extra space. Sound familiar?
The problem: Markdown was designed to look nice for people. LLMs do not need pretty, they need compact, well structured, easy to extract by section. agent-md fixes exactly that: a Rust CLI that makes Markdown friendly for LLMs, saves tokens, and stays readable for humans.
What Is Agent-md?#
Explain like you are 10: imagine packing lunch for a friend. Humans like a fancy box with many decorated compartments, robots just want one compact box with clear labels where each compartment opens directly. agent-md packs that lunchbox for robots.
Concretely, agent-md is:
- A fast Rust CLI that formats and lints Markdown for AI agents, single binary
- A Rust library (
agent_md) withformat_markdown,parse_markdown,validate_markdown - A VS Code extension called Agent-MD Formatter, with format on save
- Every command returns JSON for easy LLM parsing, plus a
--humanflag for people
Current version is 0.2.16, install with cargo install agent-md or build from source.
Why Normal Markdown Wastes Tokens?#
LLM-generated Markdown is often wasteful:
- Decorative bold
**bold**and italic markers add no meaning for machines - Wide tables with long separators
|----------|instead of|---| - Comments in code blocks with many spaces:
bun dev # run server - Repeated blank lines, horizontal rules
---, 4-space indents in normal text - Useless links like
[https://example.com](https://example.com) - Diagrams drawn with box characters and sketchy folder trees, hard to parse
Every time an LLM reads the file, you pay a token tax for that decoration. Across a repo with many docs, it adds up fast.
How Does Agent-md Work?#
It is not a simple line formatter. agent-md uses structured parsing:
Main steps:
- Preserve YAML frontmatter at the top exactly
- Detect each block: headings, code, tables, lists, HTML, paragraphs
- Format each type with context-aware, token-saving rules
- Validate with the linter, return JSON with
valid,errors,warnings
Agent-md Writing Rules#
The linter has 17 rules in two groups. Errors block file writes, warnings should be fixed.
Common error rules:
no-bold: no**bold**or__bold__outside code, see example belowsimple-table: max 5 columns, separator must be|---|, strip alignment colonstable-trailing-spaces: no extra trailing spaces inside table cellsno-ascii-graph: no box-character diagrams, use CSV, JSON, Mermaid, or listsheading-structure: single H1, no skipped levels from H1 to H3code-blocks: code needs a language tag and a closing fencelist-formatting: consistent markers, no empty itemsspace-indentation: max 2 spaces in normal text, code is exemptno-useless-links: link text must differ from the URL
Example for the no-bold rule:
This line fails because it has double stars.
Replace with plain text, or use a heading, or use code.
Code blocks may keep their original syntax.textWarning rules cover duplicate headings, multiple blank lines, missing blanks around headings, missing H1 at the top, missing final newline, hard tabs, and trailing spaces.
Full details live in docs/markdown-writing-rules.md in the source repo.
Install#
cargo install agent-md
# Or build from source
cargo build --release
# Binary at target/release/agent-md
# Use as Rust library
# Cargo.toml: agent-md = "0.2.16"bashuse agent_md::{format_markdown, validate_markdown};
let input = "# Heading\n\nSome text with *emphasis*.";
let formatted = format_markdown(input);
let result = validate_markdown(&formatted);
assert!(result.valid);rustReal Use: Format and Lint#
Format one file or a whole directory, respecting .gitignore and .markdownlintignore:
agent-md README.md
agent-md fmt README.md
agent-md fmt .
# Inspect resolved config for a file
agent-md config path/to/document.md
# Inspect merged ignore rules
agent-md ignorebashLint returns JSON so agents can read it directly:
agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.mdbashExample output when a file passes:
{
"valid": true,
"errors": [],
"warnings": []
}jsonBefore and after for tables:
| Function | Arguments | Return Type | Description |
-|----------|-----------|-------------|-------------------------------|
-| `add()` | a, b | i32 | Adds two numbers |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |diffComments in code blocks get collapsed spaces:
-bun i # Install dependencies
-bun run dev # Run the development server
+bun i # Install dependencies
+bun run dev # Run the development serverdiffBy default the formatter also strips bold markers, compacts blank lines, collapses spaces, removes horizontal rules, removes emphasis, minifies HTML to one line, adds text to unlabeled code blocks, drops empty list items, and normalizes list indent to 2 spaces.
Read One Section, Not the Whole File#
This is the best feature for agents: no need to read a 700-line README to get one section.
# Check structure first
agent-md headings README.md
agent-md read README.md --field headings
# Read only the Development section
agent-md read README.md --content "## Development"
# Read nested sections
agent-md read README.md --content "## Development > Build"
# Get single fields
agent-md read README.md --field content
agent-md read README.md --field word_count
# Search, stats, JSONL
agent-md search README.md "TODO"
agent-md stats README.md
agent-md to-jsonl README.mdbashSuggested agent workflow:
# 1. Get structure
agent-md read README.md --field headings
# 2. Find what to change
agent-md search README.md "TODO"
# 3. Validate before writing
agent-md lint --content "# New Title\nValid content"
# 4. Write with validation
agent-md write README.md "# New Title\nValid content"
# 5. Replace one section only
agent-md write-section README.md --section "## Development" --content "New content"bashOther write commands: write, append, insert, delete, write-section, list. The write command validates first, so it is hard to create off-spec files.
Plug Into Your Agent Workflow#
Add one line to AGENTS.md and agents follow it:
After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate before done.
On task completion, update docs, update README.md, and write unit tests.textOr tell agents briefly: use the agent-md CLI for reading, writing, and editing Markdown instead of direct file edits. The source repo has docs/llm-agent-rule.md with full integration guidance.
For VS Code, install Agent-MD Formatter and enable format on save for Markdown:
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "agent-md.agent-md-formatter"
}
}json[!TIP] Run
agent-md fmtbefore committing LLM-generated docs. You keep all information, cut about 20% tokens in many cases, LLMs read faster and you pay less.
When Not to Use It?#
- Docs made for beautiful human printing with fancy table alignment: keep the human version, generate a compact agent version
- ASCII diagrams as team culture: move to Mermaid so both humans and machines can read
- Files already valid: if
lintsays valid, no need to reformat
References#
- Main repo: loclv/agent-md on GitHub ↗
- Rust package: agent-md on crates.io ↗
- Markdown rules:
docs/markdown-writing-rules.mdin theagent-mdrepo - Agent guide:
docs/llm-agent-rule.mdin theagent-mdrepo - Extension: Agent-MD Formatter on VS Code Marketplace ↗
- Related standard: llms.txt ↗