Portable annotations for any document, in any editor.

annox is an open format for highlights, comments, and suggested edits. They're stored as plain files next to your document, so they travel with it through git and keep their place while the text changes. People and AI agents can review the same file, from any editor or tool that supports the format.

Install GitHub

This is annox-core running in your browser. Edit the text and watch the notes follow it.

Plain files, not a service

Every change is one immutable JSON event in .annox/. Commit it with the document. Merges don't conflict, because nothing is ever rewritten.

Anchors that survive edits

Each note stores its position and the quoted text with some context. When the document changes, a fixed search finds it again, or reports it as orphaned instead of guessing.

One server, any editor

Like LSP, annox lsp does the work once. Plain LSP editors get diagnostics and code actions. The Neovim plugin and the VS Code extension cover the full workflow.

Install

Linux, macOS, and Windows. The agent skill teaches Claude Code, Codex, Gemini CLI, and other agents to use the CLI.

$ curl -fsSL https://gaardhus.github.io/annox/install.sh | sh

From scripts and agents

The CLI targets text by quoting it, so an agent can review a file without counting characters.

# Comment on a passage, found by quoting it
annox comment paper.md \
  --quote "the bound is tight" --body "Cite Lemma 4?"

# Suggest an edit; commands print JSON with the new id
id=$(annox suggest paper.md \
  --quote "teh" --replace "the" | jq -r .id)

# Apply the suggestion to the file
annox accept "$id"

Or write @claude in a comment, and Claude Code answers it while you work, with a reply or a suggested edit. Set it up