Coding agents generate plans and diffs at machine speed. Teams need human review infrastructure at the same pace. Plannotator treats agent output as first-class artifacts requiring annotation UI, team sharing, and one-click feedback channels. It supports 9 major coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, Pi) and runs locally in the browser. The tool exposes a gap: autonomous coding tools lack the collaborative review layer that makes human development reliable.
The Missing Layer Between Agent Output and Production Merge
Most coding agents stop at file writes. They generate plans, produce diffs, and wait for the next prompt. The feedback loop depends on developers reading terminal output or inspecting file changes in their editor. This works for solo experiments but breaks down when teams need to:
- Annotate specific lines in a proposed plan before the agent writes code
- Share agent-generated artifacts with non-technical stakeholders
- Track which comments triggered re-execution versus which were ignored
- Maintain a history of plan revisions and human interventions
Plannotator fills this gap by intercepting agent output and routing it to a browser-based review surface. The architecture assumes agents produce three artifact types: Markdown plans, code diffs, and HTML previews. Each type gets a dedicated review mode with annotation tools and a feedback channel back to the agent.
Architecture: Hooks, Artifacts, and Feedback Channels
Plannotator avoids agent-specific integrations by relying on a common pattern: agents expose hooks or commands that run at lifecycle events. The tool registers itself as a handler for plan generation, code completion, and artifact creation. When an agent triggers a hook, Plannotator captures the output, writes it to a local directory, and opens a browser tab pointing to a static review server.
Artifact Capture Flow
- Agent executes a plan generation step
- Hook fires with plan content (Markdown, JSON, or structured text)
- Plannotator writes artifact to
~/.plannotator/artifacts/{session_id}/plan.md - Local HTTP server (port 3000 by default) serves the review UI
- Browser opens
http://localhost:3000/review/{session_id} - User annotates, comments, and clicks “Send Feedback”
- Feedback writes to
~/.plannotator/feedback/{session_id}.json - Agent polls feedback directory or receives webhook notification
- Agent reads feedback and adjusts next execution step
The same flow applies to code diffs and HTML artifacts. The key insight: agents already produce structured output. Plannotator just adds a viewing layer and a feedback file that agents can consume.
State Model for Annotations
Each review session tracks:
- Artifact ID: Unique identifier for the plan, diff, or HTML file
- Revision number: Increments when the agent regenerates the artifact
- Annotations: Array of
{line_number, comment, timestamp, author} - Feedback status:
pending,sent,acknowledged,resolved
Annotations persist in a local SQLite database (~/.plannotator/annotations.db). When a user adds a comment, the UI writes to the database and updates the feedback JSON file. When the agent regenerates the artifact, Plannotator creates a new revision and links old annotations to the new line numbers using a diff-based reconciliation algorithm.
Multi-Agent Support Without Custom Integrations
Plannotator supports 9 agents without writing agent-specific code. The trick: it provides a generic hook interface and documents how to wire it into each agent’s configuration.
For Claude Code:
{
"hooks": {
"onPlanGenerated": "plannotator capture --type plan --agent claude",
"onCodeComplete": "plannotator capture --type diff --agent claude"
}
}For Copilot CLI:
gh copilot suggest --hook-plan "plannotator capture --type plan --agent copilot"Each agent’s configuration file or CLI flags allow external command execution at lifecycle events. Plannotator’s capture command accepts a standard set of flags (--type, --agent, --session-id) and reads artifact content from stdin or a file path. This design shifts integration burden to the user but avoids maintaining 9 separate plugins.
Review Modes and Security Boundaries
Plannotator offers three review modes, each with different security and deployment considerations.
| Review Mode | Artifact Type | Security Boundary | Deployment Shape |
|---|---|---|---|
| Markdown Review | Plans, specs, docs | Local filesystem only | Single-user, localhost:3000 |
| Code Review | Diffs, PRs | Local filesystem, optional Git remote | Single-user or team via ngrok |
| HTML Artifacts | Rendered previews | Sandboxed iframe, no external requests | Single-user, CSP-restricted |
Markdown Review
Displays agent-generated plans with inline annotation tools. Users click a line, type a comment, and hit “Send Feedback.” The UI writes a JSON file to the feedback directory. The agent reads the file on the next execution cycle and adjusts its plan.
Security: No network access required. All data stays on the local machine. The review server binds to 127.0.0.1 by default.
Code Review
Shows diffs with syntax highlighting and side-by-side comparison. Users can annotate specific lines, approve changes, or request modifications. The feedback file includes line numbers, file paths, and suggested edits.
Security: If the user enables team sharing, Plannotator can push annotated diffs to a Git remote or expose the review server via a tunnel (ngrok, Tailscale). This introduces a trust boundary: anyone with the tunnel URL can view the diff. The tool does not include authentication or access control. Teams must rely on network-level security (VPN, SSH tunnels) or accept that shared links are public.
HTML Artifacts
Renders agent-generated HTML in a sandboxed iframe. The iframe has a strict Content Security Policy: no external scripts, no form submissions, no navigation. Users can annotate the rendered output by clicking elements and leaving comments. The feedback file includes CSS selectors and bounding box coordinates.
Security: The iframe sandbox prevents malicious HTML from accessing the parent page or making network requests. However, the agent can still generate HTML that exfiltrates data via image tags or CSS background URLs. Plannotator blocks these by default but offers a --allow-external-resources flag for cases where the agent needs to load fonts or images from CDNs.
Feedback Loop Closure: From Annotation to Agent Re-Execution
The feedback loop has three failure modes:
- Agent ignores feedback: The agent polls the feedback directory but does not incorporate comments into the next execution. This happens when the agent’s prompt does not include instructions to read feedback files.
- Feedback file format mismatch: The agent expects a different JSON schema than Plannotator produces. This requires manual schema mapping or a custom feedback adapter.
- Annotation drift: The agent regenerates the artifact with significant changes, and Plannotator’s line-number reconciliation fails. Old annotations point to incorrect lines in the new revision.
To mitigate these, Plannotator includes a feedback validation step. Before writing the feedback file, the tool checks that the agent’s expected schema matches the generated JSON. If not, it logs a warning and offers to generate a schema adapter.
For annotation drift, the tool uses a diff-based reconciliation algorithm borrowed from Git’s merge logic. When the agent regenerates an artifact, Plannotator computes a diff between the old and new versions, then adjusts annotation line numbers based on added or removed lines. This works well for small changes but breaks down when the agent rewrites entire sections.
Deployment Shape and Observability
Plannotator runs as a local HTTP server with no external dependencies. The server is a single TypeScript binary compiled with Bun. It listens on localhost:3000 and serves static HTML, CSS, and JavaScript. The review UI is a client-side React app that communicates with the server via REST endpoints.
Observability Hooks
The tool logs every annotation, feedback submission, and artifact capture to a structured log file (~/.plannotator/logs/activity.jsonl). Each log entry includes:
- Timestamp
- Session ID
- Agent name
- Artifact type
- User action (annotate, send feedback, approve)
- Feedback status
Teams can pipe this log to a centralized logging system (Loki, Elasticsearch) to track agent performance and human intervention patterns. The log format is JSON Lines, so it integrates with standard log aggregation tools without custom parsers.
Scaling to Team Workflows
For single users, Plannotator runs on the local machine with no configuration. For teams, the deployment shape changes:
- Shared review server: One team member runs the server on a persistent machine (EC2, DigitalOcean Droplet) and exposes it via a reverse proxy (Caddy, Nginx). Other team members configure their agents to send artifacts to the shared server’s API endpoint.
- Artifact storage: Instead of writing to
~/.plannotator/artifacts, the server writes to a shared S3 bucket or network filesystem. Agents upload artifacts via the API, and the review UI fetches them from the shared storage. - Authentication: The server adds HTTP Basic Auth or OAuth2 to restrict access. This requires modifying the server code or deploying behind an auth proxy (Authelia, Keycloak).
The 484 forks suggest teams are customizing the deployment for their needs. The core tool does not include multi-user features, so teams must build them or accept the single-user model.
When Large Diffs Become a Bottleneck
The code review mode struggles with large diffs (>1000 lines). The browser-based UI loads the entire diff into memory and renders it as a single HTML document. For diffs with thousands of lines, this causes:
- Slow initial load: The browser takes 5-10 seconds to parse and render the HTML.
- Laggy annotations: Clicking a line to add a comment triggers a re-render of the entire diff.
- Memory pressure: The React app holds the diff in state, and large diffs consume 100-200 MB of heap.
Plannotator does not chunk diffs or implement virtual scrolling. For large changes, users must either:
- Split the agent’s work into smaller tasks that produce smaller diffs
- Export the diff to a file and review it in a native editor
- Accept the performance hit and wait for the UI to load
This is a known limitation. The tool prioritizes simplicity over performance. Adding virtual scrolling or diff chunking would require a more complex rendering pipeline and state management layer.
Technical Verdict
Use Plannotator when:
- You run coding agents locally and need a visual review layer before merging changes
- Your team wants to annotate agent-generated plans and share feedback without switching tools
- You need a lightweight, self-hosted solution with no external dependencies
- You work with multiple coding agents and want a unified review interface
Avoid Plannotator when:
- Your diffs regularly exceed 1000 lines and you need fast, responsive UI
- You require built-in authentication, access control, or audit logs for compliance
- Your agents do not expose lifecycle hooks or you cannot modify their configuration
- You need real-time collaboration (multiple users annotating the same artifact simultaneously)
The tool shines for solo developers and small teams who want to add human oversight to agent workflows without deploying a full code review platform. It exposes the missing feedback loop but does not replace GitHub PR reviews or GitLab merge requests. Think of it as a pre-merge annotation layer, not a replacement for your existing review process.