@nakedved/ano

### 🚨🚨 Beta release out now!! 🚨🚨 # Ano **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. ## Features - **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 ## Quick Start ```bash # Install globally npm install -g @vedpawar/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 ``` ## Installation ### From npm (Recommended) ```bash npm install -g @vedpawar/ano ``` ### From source ```bash git clone https://github.com/vedpawar2254/Ano.git cd Ano npm install npm run build:all npm link ``` ## CLI Commands ### Annotations | Command | Description | |---------|-------------| | `ano annotate <file>:<line> "msg"` | Add annotation to a specific line | | `ano annotate <file>:<start>-<end> "msg"` | Add annotation spanning multiple lines | | `ano list <file>` | List all annotations for a file | | `ano resolve <file> <id>` | Mark annotation as resolved | | `ano reply <file> <id> "msg"` | Add threaded reply | | `ano delete <file> <id>` | Delete an annotation | | `ano sync <file>` | Sync annotation positions after file changes | ### Quick Shortcuts | Command | Description | |---------|-------------| | `ano lgtm <file>` | Quick approve ("Looks good to me") | | `ano shipit <file>` | Strong approve ("Ship it!") | | `ano nit <file>:<line> "msg"` | Minor nitpick (won't block) | | `ano block <file>:<line> "msg"` | Add blocker (will block) | | `ano q <file>:<line> "msg"` | Quick question | ### Approvals & Checks | Command | Description | |---------|-------------| | `ano approve <file>` | Add approval with optional title | | `ano approve <file> --title "Tech Lead"` | Approve with a title (for role-based gates) | | `ano check <file>` | Verify approval requirements (exit 0/1) | | `ano check <file> --required 2` | Require specific number of approvals | | `ano check <file> --require-title "Tech Lead"` | Require approval from specific title | | `ano check <file> --require-role lead` | Require approval from specific team role | | `ano check <file> --soft` | Warn but don't block | | `ano check <file> --override --reason "msg"` | Bypass with audit trail | | `ano check <file> --json` | Output result as JSON | ### Version Comparison | Command | Description | |---------|-------------| | `ano diff <file>` | Show changes from previous version | | `ano diff <file> --json` | Output diff as JSON | ### Team Management | Command | Description | |---------|-------------| | `ano team init [name]` | Initialize team configuration | | `ano team add <email>` | Add team member | | `ano team remove <email>` | Remove team member | | `ano team list` | List team members and requirements | | `ano team roles` | Show available roles | ### Web Viewer | Command | Description | |---------|-------------| | `ano serve <file>` | Start web viewer on localhost:3000 | | `ano serve <files...>` | View multiple files with tab switching | | `ano serve <file> --port 8080` | Use custom port | | `ano serve <file> --no-open` | Don't open browser automatically | ## Web Viewer Features The web viewer provides a rich interface for reviewing annotated files: ### Keyboard Shortcuts | Key | Action | |-----|--------| | `j` / `↓` | Next annotation | | `k` / `↑` | Previous annotation | | `r` | Resolve selected annotation | | `Shift+D` | Delete selected annotation | | `a` | Add annotation at selected line | | `/` | Focus search | | `?` | Show keyboard shortcuts help | | `Esc` | Close modal / deselect | ### Views - **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) ### Sharing - **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 ### Inline Editing Double-click any line to edit it directly. Changes are saved automatically. ### Text Selection Select text across lines to add annotations to specific ranges. ### Real-time Updates The viewer uses Server-Sent Events (SSE) to automatically refresh when files or annotations change. ## Claude Code Integration ### MCP Server Add to your Claude Code settings (`.claude/settings.json`): ```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 ### Approval Gate Hook Block Claude from executing plans without approval: ```json { "hooks": { "PreToolUse": [ { "matcher": "Write", "command": "ano check PLAN.md --quiet" } ] } } ``` #### Advanced Hook Examples Require Tech Lead approval: ```json { "command": "ano check PLAN.md --require-title 'Tech Lead' --quiet" } ``` Require 2 approvals from team leads: ```json { "command": "ano check PLAN.md --required 2 --require-role lead --quiet" } ``` Soft gate (warn but don't block): ```json { "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 Configuration Team config is stored in `.ano/config.json`: ```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"] } } ``` ### Requirements Options | Field | Description | |-------|-------------| | `minApprovals` | Minimum number of approvals required | | `minWeight` | Minimum total weight of approvals (based on role weights) | | `requiredRoles` | Roles that must approve (matches team member roles) | | `requiredTitles` | Titles that must approve (matches approval titles) | Team membership is **advisory only** - anyone can approve, but `ano check` shows who is/isn't in the team. ## How It Works ### Annotation Storage 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. ### Content Anchoring 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. ### Shareable URLs 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` ### Authentication **No login required.** Ano uses your git identity: ```bash git config user.name # Your name git config user.email # Your email ``` This makes Ano trust-based (same as git commits). ## Workflow Example ``` ┌─────────────────────────────────────────────────────────┐ │ 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* │ └─────────────────────────────────────────────────────────┘ ``` ## Project Structure ``` 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 ``` ## Annotation Types | Type | Purpose | Blocks Execution | |------|---------|------------------| | `blocker` | Must resolve before proceeding | Yes | | `concern` | Risk or issue identified | No | | `question` | Clarification needed | No | | `suggestion` | Improvement idea | No | ## License MIT ## Contributing Contributions welcome! Please open an issue or PR.