Plan
Checkout rewrite Approved
41files read
2services
1page
Coupon migration ships next release.note from you
What you and your agent make together
The chat ends.
The artifact stays.
A plan you approve, a report you forward, a worksheet you answer. Your agent writes a short Markdown file; artifacts-cli renders it as one polished HTML page that you read, mark up and send back.
$npm i -g @phnx-labs/artifacts-cli
See how it works
Apache-2.0 · Node 20 or later
youPlan the checkout rewrite. Keep it to one page.
claudeRead 41 files. Two services hold most of the dead code.
claude
artifacts render plan.mdyouApproved. Ship the coupon migration later.
---
kind: plan
title: Ship the Markdown renderer
status: draft
agent: claude
---
## Why
Agents spend most of their output
rebuilding page chrome for every plan.
```stats
2,391 | Markdown tokens
1 | HTML file
2 | Themes
```
```explorer
{ "title": "Where the cleanup is",
"metric": { "unit": "%", "max": 100 },
"items": [
{ "label": "Web", "value": 25 },
{ "label": "API", "value": 10 } ] }
```
```diff
- agent writes 25,028 tokens of HTML
+ renderer owns layout, theme, provenance
```
--- kind: plan · title · status · agent ---
Plan
Ship the Markdown rendererDRAFT
## Why …
Why
Agents spend most of their output rebuilding page chrome for every plan.
```stats …
2,391Markdown tokens
1HTML file
2Themes
```explorer …
Where the cleanup is
Web25%
API10%
```diff …
- agent writes 25,028 tokens of HTML
+ renderer owns layout, theme, provenance
Scroll, or pick a step. Each block of Markdown becomes its component.
Three commands
Scaffold. Preview. Share.
$ artifacts new plan --out plan.md wrote plan.md $ artifacts check plan.md error:2 Frontmatter field "surface" is required for plans. agent adds surface: cli and checks again $ artifacts check plan.md ok
$ artifacts render plan.md --open wrote plan.html served locally the agent saves plan.md, the open page re-renders
The other half
The page talks back.
Readers don't reply in a chat. They highlight a line, leave a note or answer a worksheet field on the page itself, then export it. The agent reads it with one command and revises the Markdown.
Worksheet
Checkout rollout Pending
Rollout
Migrate legacy coupon codes in the same release.
Your note Ship the coupon migration later.
Answer, add a note, or both.
waiting for your export
History
Every version stays.
Each render is saved on your machine. Step back through what the agent wrote and what you changed, and reopen any version without touching the source.
Worksheet
Checkout rollout Pending
Rollout
Migrate legacy coupon codes in the same release.
Your note Ship the coupon migration later.
Keep the legacy coupon field?
Answered: no
- r1 draft
- r2 your answer
- r3 revised
r3: claude moved the migration after reading your note.
Gallery
Real renders, not mockups.
Every tile is a render of a file in the repository's examples/ folder. Each page is a single HTML file that works offline, in light and dark. Point at a tile to see the fence that made it.
The agent wrote
```explorer
{ "title": "Where the cleanup is",
"metric": { "unit": "%", "max": 100 },
"items": [ { "label": "Web", "value": 25 }, … ] }
```Drill-down rows from a JSON fence.
How it works
The agent writes the content. The renderer writes the page.
The agent never writes component HTML, CSS or JavaScript. It writes a few lines of data, and the renderer builds the finished, interactive component.
--- kind: visual title: Where the dead code is --- ## Story Most removable code sits in two services. ## Figure ```explorer { "title": "Removable code", "metric": { "label": "Removable", "unit": "%", "max": 100 }, "items": [ { "label": "Web", "value": 25 }, { "label": "API", "value": 10 } ] } ```
01
It learns the format from the CLI
The artifacts skill teaches the workflow, and artifacts components --json prints each component's input with an example to copy.
02
Mistakes come back with line numbers
artifacts check rejects unknown fields, missing sections, out-of-range values and unsafe HTML before anyone reads the page.
03
The renderer adds everything else
Layout, light and dark themes, the cover, contents, collapsible sections, code highlighting, math, link previews and provenance from git.
04
Your brand, set once
Put your colors and fonts in DESIGN.md. Every artifact from every agent uses them.
Why
A tenth of the tokens. One look. Checked first.
2,391tokens of Markdown for the example plan
25,028tokens for the same page written as HTML
Any agent
Claude, Codex, Gemini and others render through the same design, so a page looks the same whichever agent wrote it.
Components from fences
explorer, bar-chart, diff, excerpt and field take JSON, a table or a single line.
Cites real code
An excerpt reads the lines from your git checkout and links them to the exact commit, so they can't be misquoted.
Built for reading
A contents rail, collapsible sections, link previews, a references list, highlights and notes.
One file, anywhere
The HTML works offline. Keep it in your repository, reopen earlier versions from local history, or share a link.
Safe by default
Embedded HTML and SVG are sanitized, and a page is scanned for emails and credentials before it is published.
Install
Two commands.
Needs Node 20 or later.
npm i -g @phnx-labs/artifacts-cli
agents skills add gh:phnx-labs/artifacts-cli \ --names artifacts --agents claude,codex -y