Skip to content
agent-md

Introduction to agent-md

What is agent-md?

Section titled “What is agent-md?”

agent-md is a fast, specialized Markdown editor, linter, and formatter engineered for LLMs, autonomous coding agents, and automated AI pipelines.

Standard Markdown was conceived to be read comfortably by human eyes in text editors and rendered into HTML. Because of this, it contains stylistic padding, decorative characters, vertical table alignment spaces, and visual artifacts (like box-drawing directory trees and double asterisks).

While humans appreciate these visual flourishes, Large Language Models (LLMs) do not need them. In fact, every aesthetic element consumes extra tokens, increases context window usage, slows down inference, and raises API costs.

agent-md solves this by introducing a clean, compact, AI-friendly Markdown format along with high-performance tooling written in Rust.

Why This Tool Exists

Section titled “Why This Tool Exists”

Many documents today are generated by LLMs or consumed repeatedly by AI agents during multi-turn coding tasks. When an AI agent inspects repository documentation, reads system instructions, or scans AGENTS.md and README.md files, it repeatedly pays a token tax for human-oriented formatting.

The Problems

Section titled “The Problems”
  1. Token Waste: Formats like padded table columns, bold tags (**bold**), multiple consecutive blank lines, and decorative ASCII boxes add tokens without conveying additional semantic meaning.
  2. Inefficient Parsing: LLMs spend attention tokens interpreting purely visual spacing rather than core technical information.
  3. All-or-Nothing Edits: Conventional file-editing tools require agents to read and rewrite entire multi-thousand-line files just to change a single section or paragraph. This consumes massive context and risks hallucinated regressions.
  4. Recurring Costs: As agent loops run dozens or hundreds of iterations, the token penalty multiplies across every single read and tool call.

The Solution

Section titled “The Solution”

agent-md provides:

  • Minimalist Formatting: Formats Markdown documents to remove redundant visual whitespace and decorations while keeping text clean and readable.
  • Section-Level Operations: Commands like read --content "## Section" and write-section allow agents to fetch and update exact headings without touching the rest of the document.
  • Machine-First JSON Output: Every CLI subcommand returns structured JSON (with line numbers, error locations, and parsed metadata) tailored for programmatic agent digestion.
  • Automated Validation: Built-in lint rules reject syntax that wastes tokens or confuses LLMs (unclosed code fences, complex tables, excessive indentations).
  • SIMD Hardware Acceleration: Employs ARM NEON and x86_64 AVX2/SSE2 vectorization to parse documents in microseconds.

Visual Comparison: Before & After

Section titled “Visual Comparison: Before & After”

Padded Tables

Section titled “Padded Tables”

Conventional Markdown tables often use extra spaces and alignment colons to align text in monospace editors:

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

Formatted with agent-md:

| Function | Arguments | Return Type | Description |
|---|---|---|---|
| `add()` | a, b | i32 | Adds two numbers |
| `sub()` | a, b | i32 | Subtracts numbers |
  • Trailing and leading padding inside cells is stripped.
  • Separator rows are normalized to |---|---|, stripping unnecessary : alignment colons.
  • Escaped pipes (\|) and code spans are preserved intact.

Code Block Comments

Section titled “Code Block Comments”

Shell code blocks frequently contain comments padded far to the right:

Terminal window
bun i # Install dependencies
bun run dev # Run the development server
bun run test # Run test suite

agent-md collapses excessive spacing down to a single space while preserving leading line indentation.

Directory Structures

Section titled “Directory Structures”

Visual directory trees with multi-character box branches (├──, └──, spacer lines │) consume substantial token overhead:

my-project/
├─src/
│ ├─main.rs
│ └─lib.rs
├─Cargo.toml
└─README.md

agent-md automatically compresses branch markers from ├── to ├─ and └── to └─, strips redundant vertical filler lines, and normalizes nested indentation.

Core Benefits

Section titled “Core Benefits”
Benefit Human Impact LLM & Agent Impact
Token Reduction Document remains clean and readable Saves up to 15–20% tokens per document pass
Speed & Latency Instant formatting (sub-millisecond) Faster prompt reading and quicker response times
Context Window Less vertical clutter More room in the context window for code and reasoning
Accuracy Clean structure Fewer formatting-induced parsing hallucinations

Next Steps

Section titled “Next Steps”