Agd

AGD — Agent Document Format

A line-oriented text format optimised for LLM agents. Sits between Markdown (too ambiguous for safe machine editing) and HTML/XML (too verbose for token-constrained contexts). Every block is independently addressable via a stable `[#id]`, so multiple agents can edit the same document without fighting over byte ranges.

@meta title="Welcome" author=alice

@h1 Hello [#intro]
@p AGD blocks start with `@` at column 0 — that is the entire syntactic story.

@h2 Features [#features]
@ul
- token-efficient vs HTML and JSON
- deterministic LL(1) parsing
- stable per-block IDs for multi-agent editing
- canonical form: byte-stable round-trip

@code lang=python [#hello]
~~~
def hello():
    return "world"
~~~

@ref #hello

Why a new format?

Markdown is great for humans. But ambiguity (CommonMark vs GFM vs MDX), implicit semantics (paragraph boundaries, nested-list rules), and lack of stable per-block addresses make it painful for LLM agents that need to edit, re-edit, and merge changes deterministically. HTML and XML solve those problems but cost ~18% more tokens and need a real DOM. JSON is unambiguous but illegible in `cat`.

AGD trades a small token premium against Markdown for:

• Deterministic LL(1) parsing — no backtracking, single-pass, ~1000 lines of Rust
• Stable per-block IDs — every editable unit has a name, not a byte offset
• Pure-data edit operations — JSON-serialisable, replayable, conflict-detectable
• Byte-stable canonical form — verified by 256+ proptest cases
• No-panic recovery — every malformed input yields a typed error

Install

cargo install --path .

The binary is called `agd`.

CLI

agd validate          file.agd                 # exit 0 if valid
agd parse --json      file.agd                 # AST as JSON
agd format --check    file.agd                 # canonical-form