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

agent-md lint README.md
# {"valid":false,"errors":[{"line":7,"column":1,"message":"Use at most 2 spaces for indentation in regular text. Code blocks are exempt from this rule.","rule":"space-indentation"},{"line":28,"column":1,"message":"Use at most 2 spaces for indentation in regular text. Code blocks are exempt from this rule.","rule":"space-indentation"},{"line":34,"column":1,"message":"Human-readable ASCII graph detected. Use LLM-readable formats instead: Structured CSV, JSON, Mermaid Diagram, Numbered List with Conditions, ZON format, or simple progress indicators","rule":"no-ascii-graph"},{"line":36,"column":1,"message":"Human-readable ASCII graph detected. Use LLM-readable formats instead: Structured CSV, JSON, Mermaid Diagram, Numbered List with Conditions, ZON format, or simple progress indicators","rule":"no-ascii-graph"}],"warnings":[]}

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.

Specific Usage Example

Input: Regular Markdown

This is a standard markdown file that many LLMs generate:

# My Project

## Overview

This is a really awesome project with many outstanding features:

| Feature | Description | Status |
|---|---|---|
| API | Complete RESTful API | ✅ Complete |
| UI | Modern user interface | 🚧 In Progress |
| Tests | Unit tests and integration tests | ✅ Complete |

### Steps to Follow

1. Clone repository
2. Install dependencies: `bun i`
3. Run server: `bun dev`

>Note: Make sure you have Node.js 22+ installed!

Output: AI-friendly Markdown via agent-md

After processing with agent-md, the content becomes cleaner:

# My Project

## Overview

This is a really awesome project with many outstanding features:

- API: Complete RESTful API (Complete)
- UI: Modern user interface (In Progress)
- Tests: Unit tests and integration tests (Complete)

## Steps to Follow

1. Clone repository
2. Install dependencies: `bun i`
3. Run server: `bun dev`

Note: Make sure you have Node.js 22+ installed.

Efficiency Comparison

# Lint regular markdown file
agent-md lint regular-markdown.md
# {"valid":false,"errors":[
# {"line":3,"message":"No bold text allowed","rule":"no-bold"},
# {"line":6,"message":"Complex table detected","rule":"simple-table"},
# {"line":15,"message":"No bold text allowed","rule":"no-bold"}
# ]}

# Lint agent-md file
agent-md lint agent-md-markdown.md
# {"valid":true,"errors":[],"warnings":[]}

Benefits:

• In some cases, reduces ~20% unnecessary tokens
• Faster LLM reading and processing
• Maintains full information content
• Easy section extraction

Add a rule or command for LLM/Agents to follow

For example, when adding a new rule, add it to the AGENTS.md file.

After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate the content before considering the task complete.

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

Or tell LLM/Agents:

Use agent-md CLI to run lint

Commands (LLM-friendly JSON output)

All commands return JSON for easy parsing. Use --human flag before the subcommand for pretty-printed output:

agent-md --human lint README.md
agent-md --human read README.md --field headings

Read a file

agent-md read <path>
# Returns: {path, content, word_count, line_count, headings}

# Extract specific field
agent-md read <path> --field <field_name>
# Available fields: path, content, word_count, line_count, headings

# Read specific section by heading path (no need to read entire file)
agent-md read <path> --content <section_path>
# Example: agent-md read README.md --content "## Development"
# Nested sections: agent-md read README.md --content "## Development > Build"

Write a file

agent-md write <path> <content>
# Returns: {success, message, document}

Write to a specific section

agent-md write-section <path> --section <heading_path> --content <content>
# Replaces existing section content or creates new section
# Example: agent-md write-section README.md --section "## Development" --content "New content"
# Nested sections: agent-md write-section README.md --section "## Development > Build" --content "New content"

Append to a file

agent-md append <path> <content>
# Returns: {success, message, document}

Insert at line

agent-md insert <path> <line> <content>
# Returns: {success, message, document}

Delete lines

agent-md delete <path> <line> [count]
# Returns: {success, message, document}

List markdown files

agent-md list <directory>
# Returns: [file paths...]

Search in file

agent-md search <path> <query>
# Returns: {query, matches: [{line, content}], total}

Get headings

agent-md headings <path>
# Returns: [{level, text, line}...]

Get stats

agent-md stats <path>
# Returns: {path, word_count, line_count, heading_count}

Convert to JSONL

agent-md to-jsonl <path>
# Returns: JSONL lines with {type, content, level, language}

Lint/Validate markdown

agent-md lint <path>
# Returns: {valid, errors: [{line, column, message, rule}], warnings: [{line, column, message, rule}]}

agent-md lint --content "# Markdown content"
# Validate content directly without file

agent-md lint-file <path>
# Returns: Human-readable linting output with errors, warnings, and summary

Format markdown

• Formats the markdown file in-place, trimming leading and trailing spaces from table cells.
• Normalizes table separator rows (e.g., |:---|:---| becomes |---|---|), removing alignment colons to save tokens.
• Preserves code block content, including relative indentation and syntax inside nested code blocks within list items.
• Collapses multiple spaces before # comments in shell code blocks (bash, sh, shell, zsh).
• Automatically converts 4 leading spaces of list item indentation to 2 spaces, and 2 leading tabs to 1 tab for sub-items, reducing token usage in nested lists.

agent-md fmt <path>
# Returns JSON data: {success, message, document}

Code Block Comment Formatting

For code blocks, the formatter automatically collapses excessive spaces before # comments while preserving indentation:

After:

```bash
echo hello # this is a comment
    # indented comment
```

Format Options

The formatter applies compact rules by default to reduce token count:

Option	Description
remove_bold	Removes **bold** and __bold__ markers
compact_blank_lines	Collapses multiple consecutive blank lines (preserves single blank lines around headings)
collapse_spaces	Collapses multiple spaces between words
remove_horizontal_rules	Removes ---, ***, ___ lines
remove_emphasis	Removes *italic* and _italic_ markers
blanks_around_lists	Ensures lists are surrounded by blank lines (configured in .markdownlint.json)
blanks_around_fences	Ensures fenced code blocks are surrounded by blank lines (configured in .markdownlint.json)
blanks_around_headings	Ensures headings are surrounded by blank lines (configured in .markdownlint.json)

Example:

agent-md fmt document.md

How it Works: Structured Parsing

Unlike simple line-based formatters, agent-md uses a structured parser that:

1. Extracts YAML Frontmatter: Preserves metadata at the beginning of the document exactly as-is.
2. Identifies Document Blocks: Recognizes headings, code blocks, tables, lists, and paragraphs.
3. Applies Context-Aware Formatting: Formats each block according to its type and your configuration options.
4. Optimizes for LLMs: Ensures the output is clean, consistent, and token-efficient while remaining human-readable.

Validation Rules

The linter enforces AI-friendly markdown standards.

Error Rules (block content)

• "no-bold": No bold text: **bold** and __bold__ are rejected, except in code blocks
• "heading-structure": Heading structure: Multiple H1 headings and skipped heading levels are rejected
• "table-syntax": Table syntax: Complex table attributes and incorrect separator format are rejected
• "simple-table-syntax": Simple table syntax: Very wide tables and inline formatting in cells are rejected
• "table-trailing-spaces": Table trailing spaces: Table cells with more than 1 trailing space are rejected
• "no-ascii-graphs": No ASCII graphs: Box drawing characters and visual patterns are rejected, even in code blocks
• "code-blocks": Code block validation: Code blocks without language specification or with missing closing fences (unclosed code blocks) are rejected, with unclosed blocks immediately aborting formatting and linting
• "list-formatting": List formatting: Inconsistent list markers and numbering are rejected
• "space-indentation": Space indentation: Excessive indentation (more than 2 spaces) in regular text is rejected (code blocks exempt)
• "no-useless-links": No useless links: Links where text equals the URL are rejected

Warning Rules (style guidelines)

• "no-duplicate-headings": No duplicate headings: Headings with same content are warned
• "no-multiple-blanks": No multiple blank lines: Multiple consecutive blank lines are warned

Detail at <docs/markdown-writing-rules.md>

Automatic validation

The write command validates content before writing to ensure AI-friendly markdown.

Running Tests

cargo test
# or
make test

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.

Why use agent-md?

• JSON output: All commands return structured JSON for easy parsing
• Built-in validation: Automatic markdown validation ensures AI-friendly content
• LLM-optimized: Designed specifically for AI agent workflows
• Consistent formatting: Enforces markdown standards for better readability

Core Usage Pattern

# Read file content
CONTENT=$(agent-md read <path> --field content)

# Read specific sections (no need to read entire file)
agent-md read <path> --content "## Section Name"
# Nested sections: agent-md read <path> --content "## Development > Build"

# Always write files with agent-md (validates first)
agent-md write <path> "<content>"

# Write to specific section
agent-md write-section <path> --section "## Section" --content "<content>"

# Search within files
agent-md search <path> "<query>"

# Get document structure
agent-md headings <path>

Integration Rule

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.

Example Workflow

# 1. Get document structure
agent-md read README.md --field headings

# 2. Search for specific content
agent-md search README.md "TODO"

# 3. Validate new content
agent-md lint --content "# New Title\nContent here"

# 4. Write validated content
agent-md write README.md "# New Title\nValid content"

Read File and Extract Fields

Use --field option (recommended):

agent-md read README.md --field path # Get file path
agent-md read README.md --field content # Get content
agent-md read README.md --field headings # Get headings
agent-md read README.md -f word_count # Short form for word count

Read "Development" section - no need LLM to read entire file:

agent-md read README.md -c="Development"
# Nested sections: agent-md read README.md -c="Development > Build"

Example Usage for LLMs

# Search for content
agent-md search /path/to/file.md "TODO"
# example:
agent-md search README.md "TODO"

# Get all headings for navigation
agent-md headings /path/to/file.md
# example:
agent-md headings README.md

# Lint a file
agent-md lint README.md
# example:
agent-md lint README.md

# Lint with human-readable output
agent-md lint-file README.md

# Validate markdown before writing
agent-md lint --content "# Title\nContent with **bold** text"
agent-md write document.md "# Title\nValid content without bold"

Example output when use "--human" flag:

{
  "valid": false,
  "errors": [
    {
      "line": 9,
      "column": 27,
      "message": "ASCII graph detected in code block. Use LLM-readable formats instead: Structured CSV, JSON, Mermaid Diagram, Numbered List with Conditions, ZON format, or simple progress indicators",
      "rule": "no-ascii-graph"
    }
  ],
  "warnings": []
}

Development

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

Development Commands

make setup # Setup development environment
make build # Build release version
make test # Run tests
make lint # Run all linting checks
make format # Format code
make clippy # Run clippy lints
make audit # Security audit
make watch # Watch for changes and rebuild
make ci # Full CI pipeline
make docs # Build and open documentation

VS Code Extension

agent-md includes a VS Code extension for formatting Markdown files.

Install from Marketplace

The extension is available on the VS Code Marketplace. Search for "Agent-MD Formatter" and install it or download it from the VS Code Marketplace.

Install from Source

1. Build the CLI first (see Installation section)
2. Build the extension:

cd vscode-extension
bun install
bun compile

3. Install in VS Code:

• Open VS Code
• Go to Extensions (Cmd+Shift+X)
• Click "..." menu > "Install from VSIX"
• Select vscode-extension/agent-md-formatter-0.1.0.vsix

Or use CLI:

code --install-extension vscode-extension/agent-md-formatter-0.1.0.vsix

Features

• Format on demand or on save
• Configurable formatting options
• Integrates with VS Code formatting system

Settings

• agentMd.path: Path to agent-md executable
• agentMd.format.removeBold: Remove bold markers (default: true)
• agentMd.format.compactBlankLines: Compact blank lines (default: true)
• agentMd.format.collapseSpaces: Collapse multiple spaces (default: true)
• agentMd.format.removeHorizontalRules: Remove horizontal rules (default: true)
• agentMd.format.removeEmphasis: Remove emphasis markers (default: true)

Usage

Open a Markdown file and use Shift+Option+F (macOS) or Shift+Alt+F (Windows/Linux) to format. Enable "Format on Save":

{
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "agent-md.agent-md-formatter"
  }
}

License

MIT