agentspecs

Your agent writes specs. agentspecs makes them real.

The problem

The first thing you do with Claude Code is spec out what you're building. PRDs, architecture docs, API designs, RFCs. But you're reading raw markdown in a chat window. No diagrams, no navigation, no structure. You copy-paste to Notion just to see it. You go 5 rounds refining and there's no diff, no versioning. You retype feedback in chat and hope Claude knows which section you mean.

The spec phase is the highest-leverage moment in a project — and we're doing it in plaintext chat bubbles.

What agentspecs does

agentspecs is a Claude Code Desktop plugin. When your agent writes a spec, it renders as a beautiful, interactive document in your browser — live. You review it, leave Figma-style comments, and Claude reads your feedback and replies in-thread. The spec becomes a real artifact that lives in your repo.

You: "Write a PRD for the auth system"

Claude: [calls create_spec → spec renders live in browser]

You: [presses C → clicks "Token Refresh" → types "Add refresh token rotation?"]

Claude: [reads feedback → replies in-thread → updates the spec]

→ Browser updates live. Version bumps. Diff shows exactly what changed.

Quick start

npm install @json437/agentspecs
npx agentspecs init

That's it. Next time you start Claude Code, it auto-discovers agentspecs. Ask your agent to write a spec and it renders at localhost.

Features

• Live preview — Markdown renders with syntax highlighting, Mermaid diagrams, and table of contents. Updates via WebSocket as Claude writes.
• Figma-style comments — Press C, click anywhere, leave feedback. Claude reads it with get_feedback and replies in-thread with reply_to_feedback.
• Version history — Every update creates a version with git context (branch, commit, dirty state). Visual diffs between any two versions. Revert to any previous version.
• Status lifecycle — Draft → In Review → Approved → Implementing → Done. Transitions are enforced.
• 8 templates — PRD, API, Architecture, RFC, Bug Report, Migration, Runbook, Design Doc. Full scaffolding with diagrams and tables.
• Dashboard — Search, filter by status, sort by date/version. See all your specs at a glance.
• Git-friendly — Everything lives in .agentspecs/ as markdown and JSON. Commit it, diff it, review it in PRs.
• Zero config — init wires up .mcp.json, launch.json, and CLAUDE.md automatically.

MCP tools

Your agent gets these tools automatically:

| Tool | What it does | |------|-------------| | create_spec | Create a spec (optionally from a template). Returns a live URL. | | update_spec | Replace content. New version, live reload. | | update_section | Update one section by heading name. | | get_feedback | Read inline comments with full reply threads. | | reply_to_feedback | Reply to a comment in-thread. | | resolve_feedback | Mark feedback as addressed. | | set_status | Move spec through its lifecycle. | | link_commit | Link an implementation commit to a spec. | | revert_to_version | Roll back to previous content. | | delete_spec | Remove a spec permanently. | | list_specs | List all specs with status. |

CLI

npx agentspecs serve          # start the web UI
npx agentspecs list           # list all specs
npx agentspecs open my-spec   # open in browser

Storage

.agentspecs/
  specs/
    auth-system/
      spec.md            # current content
      meta.json          # title, status, version, git context
      feedback.json      # comments and replies
      versions/
        v1.md
        v2.md

Designed to be committed. Specs show up in diffs, PRs, and blame.

Configuration

.agentspecs/config.json:

{ "port": 0 }

Port 0 means random available port (default). Set a specific port if you prefer. Or use env vars: AGENTSPECS_PORT, AGENTSPECS_PROJECT_DIR.

License

MIT