pxtree
Loads a webpage in headless Chromium and prints what actually rendered as a compact text tree, so an AI coding agent can check a layout without a screenshot.
A dev server page with a row of three cards, a row of three plans, a list of steps, a row of stats, an article, a form, a column of prices and a row of tiles:
$ npx -y pxtree@latest localhost:5173
1280x800 light dpr 1 ltr scroll 0/382 page 1280x1182 painted to 1134
since last run: no changes
summary: 7 findings
a.button tops 64..136 across siblings: ul.cards
div.stat tops 0..6 across siblings: div.stats
input.field starts 0..3 across siblings: form.fields
12 wider than li.plan: li.plan.featured
72 taller than li.card: li.card 3 of 3
20 shorter than div.tile: div.tile.short
gaps 16 16 24 16 between li.step: ul.steps
body 1280x1182 [pad 24][gaps 24 24 24 24 16 16 …, free 24 at end]
ul.cards 1232x208 [gaps across 16, free 600 at end][!! a.button tops 64..136 across siblings]
li.card 200x136 [pad 16][gaps 8][renders background]
h3 "Starter" 168x24 [text 19/24]
p "Short text." 168x24 @0,32 [text 16/24]
a.button "Choose" 168x40 @0,64 [pad 8 16][text 16/24][renders background]
li.card 200x136 @216,0 [pad 16][gaps 8][renders background]
h3 "Team" 168x24 [text 19/24]
p "Short text." 168x24 @0,32 [text 16/24]
a.button "Choose" 168x40 @0,64 [pad 8 16][text 16/24][renders background]
li.card 200x208 @432,0 [pad 16][gaps 8][renders background][!! 72 taller than li.card]
h3 "Business" 168x24 [text 19/24]
p "A much longer…" 168x96 @0,32 [text 16/24, 4 lines, 444 on one line]
a.button "Choose" 168x40 @0,136 [pad 8 16][text 16/24][renders background]
ul.plans 1232x56 @0,232 [gaps across 16, free 588 at end]
li.plan "Monthly" 200x56 [pad 16][text 16/24][renders background]
li.plan "Yearly" 200x56 @216,0 [pad 16][text 16/24][renders background]
li.plan.featured "Lifetime" 212x56 @432,0 [pad 16][text 16/24][renders background][!! 12 wider than li.plan]
ul.steps 1232x192 @0,312 [gaps 16 16 24 16][!! gaps 16 16 24 16 between li.step]
li.step "One" 1232x24 [text 16/24]
li.step "Two" 1232x24 @0,40 [text 16/24]
li.step.active "Three" 1232x24 @0,80 [text 16/24]
li.step "Four" 1232x24 @0,128 [text 16/24]
li.step "Five" 1232x24 @0,168 [text 16/24]
div.stats 1232x62 @0,528 [gaps across 16, free 456 at end][!! div.stat tops 0..6 across siblings]
div.stat "Revenue" 182x56 [pad 16][text 16/24][renders background]
div.stat "Orders" 182x56 @198,0 [pad 16][text 16/24][renders background]
div.stat.alert "Refunds" 182x56 @396,6 [pad 16][text 16/24][renders background]
div.stat "Customers" 182x56 @594,0 [pad 16][text 16/24][renders background]
article 1232x132 @0,614 [gaps 12]
h2 "First heading" 1232x24 [text 24/24]
p "First paragraph." 1232x24 @0,36 [text 16/24]
h2 "Second heading" 1232x24 @0,72 [text 24/24]
p "Second paragraph." 1232x24 @0,108 [text 16/24]
p.with-link "Read the first." 1232x24 @0,762 [text 16/24]
a "guide" 39x17 @69,3 [text 16/24]
form.fields 1232x108 @0,802 [gaps 8][!! input.field starts 0..3 across siblings]
input.field "Name" 208x21 [pad 1 2][text 13/15][renders background, border]
input.field "Email" 208x21 @0,29 [pad 1 2][text 13/15][renders background, border]
input.field.nudged "Company" 208x21 @3,58 [pad 1 2][text 13/15][renders background, border]
input.field "Phone" 208x21 @0,87 [pad 1 2][text 13/15][renders background, border]
div.prices 300x72 @0,934
span.price "$9" 18x24 @282,0 [text 16/24]
…×2 similar span.price 36x24..49x24
div.tiles 1232x80 @0,1030 [gaps across 16, free 900 at end]
div.tile 100x80 [renders background]
div.tile.short 100x60 @116,0 [renders background][!! 20 shorter than div.tile]
div.tile 100x80 @232,0 [renders background]
The first line is the facts line: viewport, color scheme, device pixel ratio, direction, scroll position out of the maximum, document size, and painted to, the lowest painted pixel. since last run compares with the previous run of the same URL and settings, or of the same --diff-key name. That history lives in ~/.cache/pxtree, never in your project, and --no-diff skips it.
The ul.cards line says the "Choose" buttons in the three cards have tops from 64 px to 136 px below the top of their card. The li.plan.featured "Lifetime" line says that plan is 212x56 at x 432 in its row, 12 px wider than the width its siblings share. Findings are measurements with a threshold, never verdicts. The agent decides from the code whether they are intended.
Why not a screenshot
- It gives numbers in CSS px, not pixels the model has to estimate.
- The agent reads it in one pass, as text, with the findings listed on top.
- One call covers several viewports and color schemes.
Install
pxtree drives Playwright's Chromium. Install it once, about 150 MB:
npx -y playwright@1.63.0 install chromium
pxtree itself downloads nothing and never edits your project. --channel chrome uses an installed Chrome instead. Needs Node 20 or newer.
MCP server
| Client | Install | Scope |
|---|
| Codex | codex mcp add pxtree -- npx -y pxtree@latest mcp | user, ~/.codex/config.toml |
| Claude Code | claude mcp add --scope user pxtree -- npx -y pxtree@latest mcp | user. --scope project writes .mcp.json |
| Cursor | or ~/.cursor/mcp.json / .cursor/mcp.json | user / project |
| VS Code Copilot | or code --add-mcp '{"name":"pxtree","command":"npx","args":["-y","pxtree@latest","mcp"]}' | user. .vscode/mcp.json for project, see below |
| OpenCode | ~/.config/opencode/opencode.json or opencode.json, see below | user / project |
OpenCode, opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"pxtree": { "type": "local", "command": ["npx", "-y", "pxtree@latest", "mcp"], "enabled": true }
}
}
Other clients and config files
Any MCP client that reads mcpServers:
{
"mcpServers": {
"pxtree": { "command": "npx", "args": ["-y", "pxtree@latest", "mcp"] }
}
}