Collaborative annotation and review for Claude Code

Ano enables teams to annotate, review, and approve Claude-generated plans and markdown files before execution. It integrates with Claude Code via MCP and hooks, creating a human-in-the-loop workflow for AI-assisted development.

• Inline Annotations - Add comments to specific lines with types: concern, question, suggestion, blocker
• Approval Gates - Require N approvals before Claude can proceed (via hooks)
• Title & Role-Based Authorization - Require approval from specific roles (e.g., "Tech Lead", "Security")
• Team Management - Configure team members, roles, and approval requirements
• Web Viewer - Visual interface with real-time updates, keyboard shortcuts, and inline editing
• Activity Feed - Track all annotation and approval changes chronologically
• Version Diff - Compare changes between versions, see what was added/removed/resolved
• Shareable URLs - Deep links to specific annotations or lines
• Export - Export annotated files as standalone HTML or copy for Claude
• Multi-file Support - Review multiple files in a single session
• Claude Integration - Claude can read and respond to annotations via MCP
• Git-Friendly - All data stored in sidecar JSON files alongside your code

# Install globally npm install -g @nakedved/ano # Add an annotation ano annotate plan.md:15 "Is this approach safe?" --type concern # List annotations ano list plan.md # Approve a file ano lgtm plan.md # Check approval status (for hooks) ano check plan.md # Start web viewer ano serve plan.md # Start web viewer with multiple files ano serve plan.md README.md design.md

npm install -g @nakedved/ano

git clone https://github.com/vedpawar2254/Ano.git cd Ano npm install npm run build:all npm link

The web viewer provides a rich interface for reviewing annotated files:

• Annotations - List and filter annotations by status (all/open/blockers)
• Activity - Chronological feed of all annotation and approval changes
• Changes - Diff view showing what changed since page load (added, removed, resolved)

• Copy link to view - Deep link to current annotation/line selection
• Copy for Claude - Formatted markdown summary of open annotations
• Export HTML - Standalone HTML file with all annotations embedded

Double-click any line to edit it directly. Changes are saved automatically.

Select text across lines to add annotations to specific ranges.

The viewer uses Server-Sent Events (SSE) to automatically refresh when files or annotations change.

Add to your Claude Code settings (.claude/settings.json):

{ "mcpServers": { "ano": { "command": "node", "args": ["/path/to/ano/dist/mcp/server.js"] } } }

Available MCP tools:

• read_annotations - Read annotations for a file
• add_annotation - Add a new annotation
• resolve_annotation - Mark as resolved
• approve_file - Add approval

Block Claude from executing plans without approval:

{ "hooks": { "PreToolUse": [ { "matcher": "Write", "command": "ano check PLAN.md --quiet" } ] } }

Require Tech Lead approval:

{ "command": "ano check PLAN.md --require-title 'Tech Lead' --quiet" }

Require 2 approvals from team leads:

{ "command": "ano check PLAN.md --required 2 --require-role lead --quiet" }

Soft gate (warn but don't block):

{ "command": "ano check PLAN.md --soft --quiet" }

Exit codes:

• 0 = Approved, Claude proceeds
• 1 = Not approved, Claude blocked

Override logs are written to .ano-overrides.log for audit trails.

Team config is stored in .ano/config.json:

{ "version": "1.0", "projectName": "My Project", "members": [ { "name": "Alice", "email": "alice@example.com", "role": "lead" }, { "name": "Bob", "email": "bob@example.com", "role": "reviewer" } ], "roles": { "lead": { "canOverride": true, "weight": 2 }, "reviewer": { "canOverride": false, "weight": 1 } }, "requirements": { "minApprovals": 2, "requiredRoles": ["lead"], "requiredTitles": ["Tech Lead"] } }

Team membership is advisory only - anyone can approve, but ano check shows who is/isn't in the team.

Annotations are stored in sidecar files alongside your source:

• plan.md → plan.md.annotations.json

This keeps annotations git-tracked and version-controlled with your code.

When files change, annotations can become misaligned. Ano uses content anchoring to relocate annotations:

1. Stores surrounding context (2 lines before/after)
2. Stores content hash for change detection
3. On file change, searches for matching context
4. Uses fuzzy matching (Levenshtein distance) for tolerance

Run ano sync <file> to update positions after major edits.

URLs encode the current view state:

• #annotation=<id> - Link to specific annotation
• #line=<number> - Link to specific line
• #file=<path> - Link to specific file (multi-file mode)

Example: http://localhost:3000/#annotation=abc123

No login required. Ano uses your git identity:

git config user.name # Your name git config user.email # Your email

This makes Ano trust-based (same as git commits).

┌─────────────────────────────────────────────────────────┐ │ 1. Claude generates plan.md │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 2. Team reviews (via CLI or web viewer) │ │ ano serve plan.md │ │ ano block plan.md:15 "Security concern" │ │ ano q plan.md:30 "Why this approach?" │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 3. Address feedback │ │ ano resolve plan.md <blocker-id> │ │ (Claude can read annotations via MCP and respond) │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 4. Approve │ │ ano approve plan.md --title "Tech Lead" │ │ ano lgtm plan.md │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 5. Execute │ │ User: "Execute the plan" │ │ Hook: ano check plan.md → exit 0 │ │ Claude: *proceeds with implementation* │ └─────────────────────────────────────────────────────────┘ 

ano/ ├── src/ │ ├── core/ # Core data operations │ │ ├── annotations.ts # CRUD for annotations │ │ ├── anchoring.ts # Position tracking │ │ ├── config.ts # User identity (git) │ │ ├── team.ts # Team configuration │ │ └── types.ts # TypeScript interfaces │ ├── cli/ # CLI commands │ │ ├── index.ts # Entry point │ │ └── commands/ # Individual commands │ │ ├── annotate.ts │ │ ├── approve.ts │ │ ├── check.ts │ │ ├── diff.ts │ │ ├── list.ts │ │ ├── serve.ts │ │ └── ... │ └── mcp/ # MCP server for Claude │ └── server.ts ├── web/ # Svelte 5 web viewer │ ├── src/ │ │ ├── App.svelte │ │ └── lib/ │ │ ├── FileViewer.svelte │ │ ├── Sidebar.svelte │ │ ├── AnnotationCard.svelte │ │ ├── ActivityFeed.svelte │ │ ├── DiffView.svelte │ │ └── ... │ └── dist/ # Built assets ├── hooks/ # Example hook configurations │ └── README.md └── .ano/ # Team config (per-project) └── config.json 

NPM: https://www.npmjs.com/package/@nakedved/ano

MIT

Contributions welcome! Please open an issue or PR.