mdv: A Terminal Markdown Annotation Tool Designed for Agent Workflows

mdv is a terminal-based Markdown reading and annotation tool written in Go. Its core feature is supporting anchored annotations while browsing documents in the terminal, with annotations automatically saved to a separate .notes.md file. It addresses the pain points of collaborative annotation for terminal users and adapts to agent collaboration scenarios, allowing annotations to be read and processed by agents.

In software development and technical writing, Markdown is the standard format, but options for collaborative annotation tools are limited: traditional solutions rely on online platforms or complex plugins, which are not user-friendly for terminal developers. More importantly, as AI agents are integrated into development workflows, annotation data needs structured storage and a clear anchoring mechanism to support agent reading and understanding.

The core innovation of mdv lies in its built-in annotation system: annotations are not embedded in the original document but saved to a separate .notes.md file. Its advantages include: 1. Non-intrusive (original document remains unmodified); 2. Collaborative (annotation files can be version-controlled); 3. Agent-friendly (easy for programs to parse and process).

Installation: Install via Go toolchain: go install github.com/zdim/mdv@latest. Basic Usage: Open a document: mdv path/to/doc.md. Annotations can be added at any heading while browsing, and they are automatically saved to .notes.md in the same directory. Annotation Format: Uses Markdown, with section headings corresponding to the original document's title path, e.g., annotation content under ## Implementation / Phase2 / Database changes.

mdv's design aligns with agent workflow needs: 1. Context reading (understanding feedback via annotation files); 2. Precise positioning (title paths point to specific sections); 3. Incremental processing (annotation append mode adapts to agents' incremental work). For example, a code review agent can read annotation files and make targeted modifications to code or documents.

mdv is developed in Go, offering native terminal performance advantages. Its TUI (Terminal User Interface) is built on a mature terminal library, supporting keyboard navigation and shortcuts (press ? to view references). The project structure is clear, including core reader logic and independent TUI components. The CLAUDE.md file in the repository suggests potential integration with agents like Claude.

Potential scenarios for mdv include: 1. Technical document review (terminal-based asynchronous annotation); 2. Code comment supplementation (structured feedback on README/design documents); 3. Agent collaboration (a bridge for document communication between humans and agents); 4. Knowledge base maintenance (incremental annotation updates).

mdv treats agents as intrinsic participants in workflows, providing a lightweight yet powerful document collaboration solution through structured annotations and native terminal experience. As agents become more prevalent in development, more tools designed specifically for agents like this will emerge.