Review plans and specs in your browser.

The problem

An agent can plan a feature or write a spec in seconds. But before it starts building, a human needs to review it, ask questions, request changes. The bottleneck is the review loop: the agent generates a document, the human reads it in isolation, feedback comes back as prose, the agent updates, and the cycle repeats. This is slow, lossy, and painful to automate.

What Agent Reports does

Agent Reports is a lightweight CLI that turns that loop into a single action: pipe a plan or spec to agent-reports, it opens an editable browser UI on your local machine (127.0.0.1), and the human reviews/edits/comments directly in the browser. When done, the tool emits machine-readable JSON approval (or rejection) that the agent reads and obeys. No email, no Slack threads, no round-trip summaries — direct, immediate, structured feedback.

Supports multiple input formats (markdown files, JSON payloads, stdin), multiple output viewers (Plan, Spec with 4 frameworks, Completion Report), and multi-document spec review. All rendering is local: Mermaid diagrams are vendored (no CDN), HTML is self-contained, and the server runs only on 127.0.0.1 — nothing leaves your machine.

What makes it different

• Editable review, not read-only. The human reviews in the browser but also edits and comments — no copy-paste into external documents, no context switching.
• Machine-readable approval. The review result is emitted as JSON, so the agent can parse it programmatically. Approval means proceed; rejection means stop and revise.
• Multiple spec frameworks. Support for Context-OS, Kiro/EARS, OpenSpec, and SpecKit. Let the agent pick the framework and let the human review it in the same UI.
• Local-first, zero dependencies. Pure Node.js, no runtime dependencies (not even Express), no CDN calls, no external services. Runs entirely on 127.0.0.1.
• Mermaid diagrams included. Plans with flowcharts, sequence diagrams, and swimlanes render locally without a CDN. Diagrams are editable alongside the plan text.
• Completion reporting. Completion reports show diffs per file, rollback options, and approval gates for final integration.

Install

Agent Reports is a standalone Node.js CLI. Clone the repo and run the installer:

git clone https://github.com/ruizrica/agent-reports
cd agent-reports
./install.sh

Or use npm to link it for development:

npm install
npm link
agent-reports --help