A Spec Kit extension
Axi opens a feature's spec-kit markdown as rendered web pages. Read the documents,
select any phrase to annotate, or drop a general comment. Your notes queue up and, on
one click, go back to the agent, which edits the canonical .md files while
the page live-reloads to show each change. Markdown stays the source of truth, and your
notes never leave your machine.
specify extension add axi \
--from https://github.com/d0whc3r/spec-kit-axi/releases/download/v2.0.0/axi-2.0.0.zipWorks with zero configuration. Change the version in the URL to pin a release.
specify extension add axi --force \
--from https://github.com/d0whc3r/spec-kit-axi/releases/download/v2.0.0/axi-2.0.0.zip
Run the install command again with --force to replace an installed
version. Your specs/ tree does not change.
Reviewing a spec in a chat window is awkward: you paste line ranges, describe where you mean, and hope the agent edits the right place. Axi turns the feature's markdown into a page you can read and mark up directly, so feedback is anchored to the exact text and the agent applies it without guessing.
Every artifact (spec.md, plan.md, tasks.md,
and whatever else the feature generated) renders as a web page with tables and
mermaid diagrams. Nested files such as contracts/ show up as their own
tabs.
Select any phrase to attach a note. Axi records the file, the nearest heading, and the exact text you picked, so the agent edits the right spot. Or type a general comment in the composer for feedback that spans documents.
Click Send and the whole queue goes to the agent. It edits the canonical
.md files in place, posts a one-line summary, and the page
live-reloads. It never writes a derived copy, and your notes stay on your machine.
/speckit.axi.review (/speckit-axi-review in skills-based
agents such as Claude Code) opens the review surface for the active feature, collects
your annotations and comments, and applies the queued feedback to the markdown. It does
not generate new files; it edits the feature's existing documents in place.
| Command | What it does |
|---|---|
/speckit.axi.review |
Open a feature's markdown in a browser review surface, collect annotations and
comments, and apply the queued feedback to the canonical .md files.
Optionally name the feature directory, for example
/speckit.axi.review specs/001-my-feature; otherwise the agent uses
the feature Spec Kit marks as active, then your branch, then the most recent
specs/* directory. Skills-based agents name it
/speckit-axi-review (Claude Code) or
$speckit-axi-review (Codex).
|
Spec Kit also offers a review through two optional hooks. After
/speckit.specify, the after_specify hook offers to open
spec.md. After /speckit.plan, the after_plan hook
offers to open plan.md and the other plan artifacts. Accept the offer, or
run the command later.
Under the hood, /speckit.axi.review drives a small zero-dependency Node
tool, .specify/extensions/axi/templates/web-review/axi-server.mjs, that
binds only to 127.0.0.1. The agent uses these subcommands to bridge your
browser and the markdown:
| Subcommand | Purpose |
|---|---|
start <feature-dir> |
Open or reuse a session and launch the browser. |
poll <feature-dir> |
Wait for sent notes, then print them as TOON. |
reply <feature-dir> "text" |
Show a message to the reviewer. |
end <feature-dir> |
End the session. |
stop [feature-dir] |
Shut the server down. |
Run any subcommand with --help for its flags and examples. You never call
these by hand; the agent does, while you stay in the browser.
The agent launches the surface and opens your browser at a 127.0.0.1
address. From there the loop is yours to drive: read, mark up, send, and watch the
changes land.
Each markdown file in the feature directory shows up as a tab, rendered with tables and mermaid diagrams. The renderer loads from a pinned CDN, so the pages need an internet connection; offline, the surface shows a notice.
Select any phrase and add a note: the file, the nearest heading, and the exact text are recorded for you. Or type a general remark in the composer (Enter adds it, Shift+Enter for a newline). Notes collect in the Notes panel, where you can edit or remove any before sending.
One button hands the whole queue to the agent. The status line shows whether the agent is connected and when it is processing your notes.
The agent edits the canonical .md files, posts a one-line summary of
what changed, and the document live-reloads in place. Keep reviewing, or end the
session in the browser when you are done.
You need Spec Kit >= 0.12.17 initialized (specify init) and a
feature with some markdown to review. Install directly from the latest release:
specify extension add axi \
--from https://github.com/d0whc3r/spec-kit-axi/releases/download/v2.0.0/axi-2.0.0.zipConfirm it registered:
cat .specify/extensions/.registry # 'axi' entry present
ls .specify/extensions/axi # extension files present
specify extension search axi and
specify extension info axi show the catalog entry. Install by name does
not work, because the community catalog is discovery only. See
install help.
Run the command in your Spec Kit-aware assistant. Name the feature directory, or let
the agent resolve the active feature. In Claude Code the command is
/speckit-axi-review.
/speckit.axi.review specs/001-my-featureThe agent starts a local server, opens your browser, and tells you the surface is ready.
Read the rendered documents. Select text to annotate, or type a comment, then click Send. The agent applies your notes to the markdown and the page live-reloads.
End the session from the browser, or ask the agent to stop. The agent shuts the local server down. Your markdown is updated in place; nothing else is touched.
If specify extension add axi stops with the error below, this is the fix.
It is expected behavior, not a broken release.
The error you may see
Error: 'axi' was found in the 'community' catalog, which is discovery-only
...
Don't flip such a catalog to install_allowed.
Spec Kit lists community extensions in a discovery-only catalog. That
catalog has install_allowed: false, so Spec Kit does not install from it.
Spec Kit also advises against changing that setting. Install from the release archive
instead.
specify extension add axi fail?
Spec Kit lists the extension in its community catalog, which is discovery only
(install_allowed: false). The CLI shows it but does not install it.
Install directly with --from <release-zip-url>. Full steps are in
install help.
Yes, but only the feature's markdown you are reviewing, and only as your queued
notes direct. The agent edits the canonical .md files in place and the
page live-reloads. It does not write a derived copy, and your notes stay on your
machine.
Yes, to render the pages. The renderer (marked, DOMPurify, and mermaid) loads from a pinned CDN, so a plain visit needs internet; offline, the surface shows a notice. The markdown and your notes never leave your machine.
Every .md file in the feature directory, including nested ones such as
contracts/. Known names (spec.md, plan.md,
tasks.md, constitution.md, and a few others) sort first;
the rest follow alphabetically.
No. The command is a Markdown prompt that needs a Spec Kit-aware assistant to
resolve and execute it. The review surface is a zero-dependency Node tool the
assistant launches with node; it binds only to
127.0.0.1 and has no runtime of its own beyond Node.
End it from the browser, or ask the agent to stop. The agent shuts the local server down. Starting another review reopens the surface for whatever feature you point it at.
Run the install command with the newer release URL and add --force.
Your specs/ tree does not change.
More detail in the usage guide and the wiki.