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:

• 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.

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

Validation Rules

The linter enforces AI-friendly markdown standards.

Error Rules (block content)

• No bold text: **bold** and __bold__ are rejected (errors), except in code blocks
• Heading structure: Multiple H1 headings and skipped heading levels are rejected (errors)
• Table syntax: Complex table attributes and incorrect separator format are rejected (errors)
• Simple table syntax: Very wide tables and inline formatting in cells are rejected (errors)
• No ASCII graphs: Box drawing characters and visual patterns are rejected, even in code blocks (errors)
• Code block best practices: Code blocks without language specification are rejected (errors)
• List formatting: Inconsistent list markers and numbering are rejected (errors)
• Space indentation: Excessive indentation (more than 2 spaces) in regular text is rejected (errors) (code blocks exempt)
• No useless links: Links where text equals the URL are rejected (errors)

Warning Rules (style guidelines)

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

License

MIT