agent-md - A CLI that helps you write LLM-friendly markdown

Sponsored by dopana.com

Extension in VS Code, Cursor, Devin, Antigravity

Documentation: https://agent-md-551.pages.dev

Format markdown files for LLMs and AI Agents:

agent-md README.md

An example of table formatting before and after:

 | Function | Arguments | Return Type | Description                   |
-|----------|-----------|-------------|-------------------------------|
-| `add()`  | a, b      | i32         | Adds two numbers              |
-| `sub()`  | a, b      | i32         | Subtracts numbers             |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |
+| `sub()` | a, b | i32 | Subtracts numbers |

An example of comments in code blocks before and after:

-bun i                      # Install dependencies
-bun run dev                # Run the development server
-bun run something-else     # Run something else
+bun i # Install dependencies
+bun run dev # Run the development server
+bun run something-else # Run something else

An example of file trees before and after:

 example-folder/
-├── file-1.txt
-├── file-2.txt
-└── sub-folder/
-    ├── file-3.txt
-    └── file-4.txt
+├─file-1.txt
+├─file-2.txt
+└─sub-folder/
+  ├─file-3.txt
+  └─file-4.txt

• LLM reads less and faster.
• Save more tokens.
• Save more money.

Lint markdown files for LLMs and AI Agents:

cd project-folder-name
# format recursively current directory
agent-md .

agent-md lint README.md
# {"valid":false,"errors":[{"line":7,"column":1,"message":...

Why This Tool Exists

Many markdown files today are generated by LLMs or AI agents, and they often waste a lot of tokens. When another LLM reads those files, it continues to consume unnecessary tokens. The reason is that markdown is designed to be human-friendly, so it includes elements like bold text, decorative characters, and extra spacing. These are useful for people, but not needed for LLMs.

In practice, LLMs/agents don't need to read the entire file. They only need to access specific sections (e.g., ## Development) instead of processing everything.

Problems

• Token waste: Formatting like bold text, tables, and decorative elements increases token usage without helping AI
• Inefficient parsing: LLMs still have to process visual elements like bold and ASCII art
• Redundant structure: Many elements are useful for humans (complex tables, layouts) but unnecessary for AI
• Higher cost: Every time an LLM reads the document, it pays a "token tax" for human-oriented formatting

Solution

agent-md introduces a minimal, AI-friendly markdown standard that:

• Reduces unnecessary tokens
• Keeps content structured and easy to access by section
• Remains readable for humans when needed

The goal: write once, optimize for both humans and AI—without wasting resources.

Installation

Build from source:

• Install Rust first if not already installed
• Then build the release version:

cargo build --release
# Binary at target/release/agent-md

• Add to PATH (optional):

# agent-md command
export PATH="/Users/username/w/agent-md/target/release:$PATH"

Now you can use the agent-md command from anywhere.

Or install directly via Cargo:

cargo install agent-md

Or install via Homebrew (macOS and Linux):

brew tap loclv/tools
brew install agent-md

Use as a Rust Library

Add agent-md to your Cargo.toml:

[dependencies]
agent-md = "x.y.z" # replace with actual version

Use the programmatic APIs in your application:

use agent_md::{format_markdown, parse_markdown, validate_markdown};

let input = "# Heading\n\nSome text with *emphasis*.";
let formatted = format_markdown(input);

let result = validate_markdown(&formatted);
assert!(result.valid);

Documentation

Online documentation: https://agent-md-551.pages.dev/

Detailed guides and documentation are organized in the docs/ folder:

• CLI Usage Guide: Complete command reference, section operations, formatting options, and structured parsing
• LLM / Agent Integration Rule: Integration patterns, section reads/writes, field extractions, and workflows for AI agents
• Markdown Writing Rules: Formatting standards and AI-friendly rules
• Configuration Guide: Configuration resolution, options reference, and per-file overrides
• VS Code Extension: Extension setup, settings, and keybindings
• Development Guide: Architecture, building, testing, and contribution setup
• Vietnamese Documentation: Bản tiếng Việt của README và tài liệu liên quan

Quick Usage

# Format a markdown file in-place
agent-md fmt README.md

# Lint a file with JSON output
agent-md lint README.md

# Read only a specific section by heading path
agent-md read README.md --content "## Installation"

# Extract fields (path, content, word_count, line_count, headings)
agent-md read README.md --field headings

# Search within files
agent-md search README.md "TODO"

For the complete command manual, see the CLI Usage Guide.

Rule for LLMs/Agents: Use agent-md CLI

When working with markdown files, always prefer the agent-md CLI tool over direct file editing. See docs/llm-agent-rule.md for the complete integration guideline and best practices.

RULE: When you need to read, write, or modify markdown files, use agent-md commands instead of direct file operations. The tool provides structured data and ensures content quality.

On task completion, you must update documentation (docs/), update README.md, and write unit tests for your changes.

# Core workflow
agent-md read README.md --field headings
agent-md search README.md "TODO"
agent-md lint --content "# New Title\nContent here"
agent-md write README.md "# New Title\nValid content"

VS Code Extension

agent-md is available as a VS Code extension for formatting Markdown files on demand or automatically on save.

• Install from the VS Code Marketplace.
• See the VS Code Extension Guide for full configuration, settings, and manual build instructions.

Development

See docs/DEV.md for complete development setup and guidelines.

cargo build --release # Build release version
cargo test # Run tests
cargo fmt # Format code
cargo fmt --check # Check if code is formatted
cargo clippy --all-targets --all-features -- -D warnings # Run clippy lints
cargo audit # Security audit

License

MIT