frameshot

Give your AI agent eyes. Render any component — with real imports, Tailwind, and CSS Modules resolved via Vite — directly in your terminal or AI chat. No stories. No config. Just point at a file.

<p align="center"> <img src="docs/demo.gif" alt="frameshot demo" width="720" /> </p>

Claude Code

claude mcp add frameshot -- npx frameshot-mcp@latest

<details> <summary>Cursor · VS Code · Windsurf · Cline</summary>

{
  "mcpServers": {
    "frameshot": {
      "command": "npx",
      "args": ["frameshot-mcp@latest"]
    }
  }
}

</details>

---

Using with Claude

Once installed, just tell Claude what you want:

"Render src/components/PricingCard.tsx and check the layout looks right"
"Refactor the dashboard to use CSS grid — render it before and after and make sure nothing broke"
"Show me all components in src/components/ as screenshots"

Claude will automatically call render_file, diff_component, or render_catalog as needed. No manual tool calls required.

---

Render

Point to a file. Get a screenshot. All imports resolved.

render_file("src/components/Dashboard.tsx")

<p align="center"> <img src="docs/example-output.png" alt="Rendered PricingCard with full Tailwind styling" width="280" /> </p>

Real Tailwind. Real CSS Modules. Real dependencies — not a CDN polyfill.

---

Visual diff

Catch regressions before you ship. Before / after / changed pixels — all at once.

<p align="center"> <img src="docs/diff-before.png" alt="Before" width="210" />   <img src="docs/diff-after.png" alt="After" width="210" />   <img src="docs/diff-result.png" alt="Diff" width="210" /> </p>

diff_component("src/components/MetricCard.tsx")
→ 0.7% changed

---

Tools

Tool	What it does
render_file	Render a file via Vite — full dep resolution, props support
render_component	Render a self-contained snippet (React / Vue / Svelte / HTML)
screenshot_url	Screenshot any URL — localhost, staging, prod
diff_component	Pixel diff before/after with % changed
render_responsive	Mobile + tablet + desktop in one call
render_theme	Light + dark mode side by side
audit_a11y	axe-core accessibility audit (WCAG)
render_catalog	Render every component in a directory

<details> <summary>All 18 tools</summary>

Tool	What it does
render_file	Render a project file with full Vite dependency resolution
render_component	Render a self-contained snippet → screenshot
screenshot_url	Screenshot any URL with retry and network idle wait
render_responsive	Mobile + tablet + desktop in one call
render_variants	Multiple prop/state variants at once
render_theme	Light + dark mode side by side
render_interaction	Simulate click/hover/type, then screenshot
render_grid	Multiple snippets in a labeled grid
render_matrix	Viewport × theme matrix in one call
capture_animation	Multi-frame CSS animation capture
diff_component	Before/after pixel diff with % changed
diff_reference	Compare render against a reference image (Figma QA)
audit_a11y	axe-core accessibility audit
perf_audit	DOM count, depth, render timing
render_catalog	Render all components in a directory
snapshot_save	Save a render as named baseline
snapshot_check	Compare current render against saved baseline
snapshot_list	List all saved snapshots

</details>

---

CLI

No AI client required. Use frameshot standalone:

npx frameshot render src/components/Button.tsx
npx frameshot render src/Card.tsx --props '{"title":"Hello"}'
npx frameshot catalog src/components/ --recursive
npx frameshot diff src/components/Header.tsx

Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to .frameshot/ by default.

---

GitHub Action

Free Chromatic alternative. Auto-posts before/after screenshots with diff on every PR:

# .github/workflows/visual-preview.yml
name: Visual Preview
on: [pull_request]
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: kamegoro/frameshot@main
        with:
          paths: "./src/components/*.tsx"

---

Performance

Typical measured times (varies by machine and project size):

Scenario	Time
Warm render (Vite server cached)	~200–500ms
CDN fallback (no Vite)	~120ms
Cold start (first render)	~1–3s
Subsequent renders (same session)	~200ms

Vite server is cached per project root. Browser pool stays warm between MCP calls.

---

vs. alternatives

	Storybook	Chromatic	Browser MCP	frameshot
Setup	Stories + config	SaaS signup	Browser install	npx — done
Speed	Dev server startup	Cloud round-trip	2–5s	~200ms warm
Cost	Free (labor cost)	$149–800+/mo	Free	Free forever
Stories needed	Yes	Yes	No	No
Real imports	Via Storybook	Via Storybook	No	Via Vite
Works offline	Yes	No	Yes	Yes
AI-native (MCP)	No	No	Full-page only	Component-level

---

Development

git clone https://github.com/kamegoro/frameshot.git
cd frameshot && npm install
npx playwright install chromium
npm run build && npm test

See CONTRIBUTING.md for architecture details.

---

MIT © kamegoro