.aim: an open document format for human + AI co-authoring

Status: v0.3 draft. Spec and reference tooling are published; breaking changes are possible until 1.0. v0.3 added literal per-element paint — validated inline color, background-color and border-color — so one element can be given one exact colour without touching a document-wide theme slot. v0.2 added pagination: page setup (aim:doc) and hard page breaks. Specification · Getting started · Examples

A .aim file is a single HTML document that is, at the same time:

• the rendered artifact: open it in any browser, styled, no tooling;
• the accepted current version: every block covered by a stable, uniquely-identified chunk that AI and tools can address;
• the pending-change lane: AI/human proposals carried in the file, visible to any reader, applied only on explicit accept;
• the full edit history: an append-only, invertible event log; any past version is reconstructible and verifiable against checkpoint hashes;
• derived caches (summary, TOC, embeddings, packed assets) that help agents but are never load-bearing.

Documents are increasingly written with AI, in formats designed for a single human at a single cursor. Everyone building document workflows with AI reinvents the same primitives: addressing a region of a document, tracking which edits came from the model, letting a human accept or reject them, proving what the document said before. .aim makes those primitives part of the file format itself: open, editor-agnostic, MIT.

┌──────────────────────────── one .aim file ────────────────────────────┐
│ <head>   summary + TOC cache · versioned stylesheet · theme           │
│ <body>   the accepted document (chunks + containers, renderable)      │
│          <aim-proposals>  pending AI/human changes + explanations     │
│          <aim-assets>     content-addressed packed images             │
│          history          append-only invertible event log (JSONL)    │
│          embeddings       per-chunk vectors w/ staleness hashes       │
└────────────────────────────────────────────────────────────────────────┘

Install

pip install aimformat            # zero runtime dependencies (stdlib only)
pip install 'aimformat[docx]'    # + DOCX export (python-docx)
pip install 'aimformat[mcp]'     # + MCP server: aim mcp
pip install 'aimformat[convert]' # + md/docx import-export, pdf import
pip install 'aimformat[pdf]'     # + PDF export (playwright + chromium)

The CLI installs as aim and as aimformat (same tool; the alias avoids the console-script collision with AimStack's aim experiment tracker and makes uvx aimformat work).

Sixty seconds

import aimformat as aim

doc = aim.new_document(title="Q3 Proposal")
me, bot = aim.human("ada"), aim.agent("model-id")

# direct edits append invertible history events
intro = doc.add_chunk("<p>We propose a three-year engagement.</p>", author=bot)

# the pending lane: propose → human decides
p = doc.propose_modify(intro.id,
                       f'<p data-aim="{intro.id}">Acme saves €2.1M over three years.</p>',
                       author=bot, explanation="Lead with the outcome.")
doc.accept(p.id, decided_by=me)          # or .reject(...), or accept with tweaks
doc.checkpoint("sent-to-client")         # pins a verifiable doc_hash

assert doc.verify() == []                # replay the log, check every hash
doc.save("proposal.aim")                 # canonical bytes; renders in a browser

aim lint proposal.aim     # structure + vocabulary + security + history chain
aim show proposal.aim     # chunks, pending lane, history at a glance
aim hash proposal.aim     # current doc_hash
aim normalize other.aim   # re-spell to canonical form (lossless, idempotent)

What makes this different from "HTML with extra attributes":

• Identity is part of the format. Chunk ids live in the file, edits target ids (never character offsets), and identity survives any tool.
• Byte-canonical serialization. Attribute order, class order, escaping, line structure: all specified. Equality is byte equality, diffs are string compares, and no editor's parser is the arbiter of truth.
• The history verifies. Every state-changing event carries enough to undo it. verify() replays the log backwards over a copy, byte-compares every payload (which catches out-of-band edits), and checks every checkpoint hash.
• Provenance is first-class. Every event and proposal records its actor (human / agent + exact model id / external), timestamp, batch, and a one-line explanation.

Interop: read almost anything, write Word

Ingest whatever docling can read (PDF, DOCX, PPTX, images, HTML), without adding docling as a dependency of this package:

from docling.document_converter import DocumentConverter
import aimformat as aim

result = DocumentConverter().convert("contract.pdf")
doc = aim.from_docling(result.document)      # chunks, lists, tables, figures
doc.save("contract.aim")                     # ingestion itself is history

Export back to Word with the pending lane as real tracked changes (w:ins/w:del, attributed to the proposing human or model), or resolved with a caller-chosen default:

aim.to_docx(doc, "out.docx", pending="tracked")      # reviewable in Word
aim.to_docx(doc, "out.docx", pending="accept-all")   # resolved on a copy
aim.to_docx(doc, "out.docx", pending="reject-all")

The API in one table

Actors: aim.human("ada"), aim.agent("model-id"), aim.external("tool"), parsed from strings with aim.parse_actor("agent:model-id").

For agents & LLMs

Every .aim file opens with a short agent note (spec §2.5): a declarative head comment that tells whichever LLM opens the file what it is, where the docs live, and which invariants to keep. It is informative only, by spec; nothing installs or executes because of it. The note points to https://aimformat.com/llms.txt, which condenses docs/for-agents.md, the canonical guide for agents.

The tooling on-ramps, in order of preference:

# CLI: coding agents with a shell need nothing else
aim show FILE --format json
aim propose modify FILE CHUNK_ID --html '…' --author agent:MODEL_ID
aim accept FILE PID --author human:ada
aim note FILE --check                    # CI gate for the agent note

# Agent Skill: any harness supporting the open Agent Skills standard
npx skills add tndmhq/aimformat
#   Claude Code: /plugin marketplace add tndmhq/aimformat

# MCP server: for shell-less clients (six tools, local stdio)
pip install 'aimformat[mcp]'

{ "mcpServers": { "aimformat": { "command": "aimformat", "args": ["mcp"] } } }

An id-preservation eval harness under evals/ measures how well naked LLMs respect the format's invariants with and without the agent note.

Format at a glance

The specification is one file, and it is executable: every ```aim snippet in it is linted in CI, the construct reference appendix is generated from the same registry that drives the linter and the stylesheet, and the conformance suite (tests/fixtures/) ships ok_* files that must lint clean plus nok_<CODE>_* files that must trip exactly their rule — covering a growing subset of the rulebook (every rule's firing behavior is additionally pinned in the test suite) — for third-party implementations to reuse.

Design pillars (details and rationale in the spec):

• HTML plus a closed Tailwind-vocabulary subset. Models read and write it accurately, a finite vocabulary with one versioned stylesheet kills cross-model drift, and every browser renders it for free.
• Styling has three tiers, and which one you reach for is decided by the scope of the change, not by taste: reusable roles are classes, document-wide constants are theme slots, and one element's own exact value — a position, or since v0.3 a colour — is inline style, on a closed property list with a closed grammar per property. An editing agent usually sees part of a document; the literal is the only tier that cannot repaint something it was never shown.
• Semantic chunking. Chunk boundaries are authorial; the chunk is the unit of meaning, retrieval, edit targeting, and explanation.
• Propose/accept as file primitives, with persisted attribution, explanations, accept-with-tweaks (applied vs proposed), and deterministic supersede/chain semantics.
• Docs and slides in one format. Slides are fixed-canvas containers of positioned chunks, with the same proposals and the same history.
• Security as conformance. No script, no event handlers, no dangerous URL schemes, all enforced by the linter (aim lint is the gate).

Repository map

Planned next (tracked in the spec's Future Extensions): reference viewer and PPTX import/export.

Relationship to Tndm

The format is maintained by Tndm, which builds a commercial editor on top of it, the same model as ProseMirror/Tiptap or Git/GitHub. The format itself is neutral ground: open, MIT-licensed, and designed to be adopted (and extended) by anyone, including other editors.

Contributing

See CONTRIBUTING.md, which covers how the registry, generated appendix, fixtures, and executable spec snippets fit together. AI agents: start at AGENTS.md.

License

MIT © Luca Campanella