annot

An annotation tool for human-in-the-loop AI workflows.

Platform: macOS (Apple Silicon) and Linux (NixOS/Wayland tested). Not tested on Windows.

Why

AI agents work fast, but "make it better" is a lossy feedback channel. When an agent drafts a plan, proposes a refactor, or generates code — you need a way to point at specific lines and say what you actually mean, before any of it becomes real.

annot is that moment of review. It opens a window, you shape the content with located, structured feedback, then it closes and gets out of the way.

Install

macOS:

brew install denolehov/tap/annot

git clone https://github.com/denolehov/annot.git && cd annot
pnpm install
pnpm tauri build

git clone https://github.com/denolehov/annot.git && cd annot
nix develop          # enter dev shell with all build dependencies
pnpm install
pnpm tauri build     # .app bundle at src-tauri/target/release/bundle/macos/

sudo apt-get update
sudo apt-get install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  libgstreamer-plugins-bad1.0-dev

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/denolehov/annot.git && cd annot
pnpm install
pnpm tauri build     # binary at src-tauri/target/release/annot

git clone https://github.com/denolehov/annot.git && cd annot
nix develop          # enter dev shell with all build dependencies
pnpm install
pnpm tauri build     # binary at src-tauri/target/release/annot

nix profile add path:.

Quick start

With Claude Code

macOS — add to your MCP settings (~/.claude/settings.json or project .claude/settings.json):

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

Linux — use the CLI instead:

claude mcp add --scope user annot annot mcp

Claude now has review tools (review_file, review_diff, review_content) and bookmark tools (get_bookmark, list_bookmarks). Ask it to review something and a window opens for your feedback.

Standalone

annot file.rs           # Open a file for annotation
annot --json file.rs    # Output as JSON (for agent consumption)

How it works

1. A window opens with your content (code, diff, or markdown)
2. Click line numbers to select ranges, then type your annotation
3. Weave tags into prose for structured feedback: [# VERIFY] this claim with a test
4. Select an exit mode (Tab) to signal intent — "Apply", "Reject", "Needs changes"
5. Close the window — structured annotations return to the caller

No data leaves your machine. No accounts. No cloud.

Features

Tags

Composable mini-prompts you build over time. Type / in the annotation editor to insert one:

[# VERIFY] this with a dedicated test
Make this configurable. Add a new section in @config.rs.
[# ELABORATE] on the error handling here

Tags carry semantic meaning that LLMs interpret. They appear in a LEGEND block in the output. Create your own via the command palette (:).

Exit modes

Signal intent when closing a review. Instead of just closing, indicate what should happen next.

User-defined modes persist across sessions. Agent-defined modes are ephemeral and passed via MCP:

{
  "exit_modes": [
    {"name": "Apply", "instruction": "Apply all changes exactly as annotated", "color": "green"},
    {"name": "Reject", "instruction": "Reject and explain reasoning", "color": "red"}
  ]
}

Session context

Press Shift+C to add comments that apply to the entire review — framing context like "focus on error handling, ignore style."

More

• Syntax highlighting for 50+ languages
• Mermaid diagrams rendered inline
• Portal links — embed live code from other files
• Bookmarks — save and recall annotations across sessions
• /excalidraw — draw diagrams inside annotations
• /replace — propose inline code changes

MCP tools

review_file

review_diff

*Either git_diff_args or diff_content must be provided.

review_content

get_bookmark

list_bookmarks

Keyboard shortcuts

In annotation editor:

License

AGPL-3.0