axe
SwiftUI live preview with hot-reload, and view hierarchy inspection, all from the command line.
Features
🖥️ VS Code / Cursor Extension
Open a Swift file with #Preview and the preview starts automatically. See vscode-extension/README.md.
axe is a CLI tool for running SwiftUI Previews with hot-reload support.
It works standalone, but also supports Protobuf-defined input/output schemas so you can pair it with any frontend.
As a reference implementation, a VS Code / Cursor extension is available:
https://marketplace.visualstudio.com/items?itemName=k-kohey.axe-extension
Multi-simulator management, preview frame streaming, and input forwarding are all handled by axe as the backend.
To build your own client (Emacs, Vim, web frontend, etc.), try the serve command:
axe preview serve [flags]
🤖 AI Agent Coding Support
CLI-first design enables AI agents to operate SwiftUI Previews directly.
Since every operation is available through the CLI, AI agents such as Claude Code can use axe without a GUI. The simulator runs headlessly.
A Claude Code plugin is provided with skills for capturing previews, reviewing UI, and inspecting view hierarchies — all driven autonomously by the agent. Files with multiple #Preview blocks are fully supported.
Install the Claude Code plugin:
# Register the marketplace
claude plugin marketplace add k-kohey/axe
# Install the plugin
claude plugin install axe-preview@axe
All features are accessible via the CLI, making it straightforward to capture previews from multiple processes or integrate with CI.
📸 Report
Batch-capture screenshots of every #Preview block and generate a Storybook-style report.
axe preview report captures screenshots of all #Preview blocks in the specified Swift files and outputs them as PNG, Markdown, or HTML. Useful for visual review in PRs or automated UI catalog generation. Host the generated HTML to use it as a living storybook.
🔍 View Hierarchy Inspection
Dump the UIKit/SwiftUI view hierarchy via LLDB, with an interactive TUI browser and per-view PNG snapshots.
Processing images is generally slower than processing text. The axe view command provides a text-based alternative for quickly inspecting views or helping AI agents understand view structure.
Requirements
- macOS (Apple Silicon)
- Xcode (command-line tools)
idb_companion — for headless simulator management
Install
curl -fsSL https://raw.githubusercontent.com/k-kohey/axe/main/install.sh | sh
The installer also installs idb_companion via Homebrew if not present. To install it manually:
brew install facebook/fb/idb-companion
Or download a binary from the Releases page.
Quick Start
Create a .axerc in your project root so you don't have to pass flags every time:
PROJECT=MyApp.xcodeproj
SCHEME=MyApp
Then preview any Swift file containing #Preview:
# Oneshot: capture screenshot to stdout
axe preview MyView.swift > screenshot.png
# Watch mode: hot-reload on file changes
axe preview watch MyView.swift
Usage
axe preview
Launch a SwiftUI preview on a headless iOS Simulator.
The preview command has several subcommands:
| Command | Description |
|---|
axe preview <file> | Oneshot: capture a PNG screenshot to stdout, then exit |
axe preview watch <file> | Watch for file changes and hot-reload |
axe preview serve | Run as multi-stream IDE backend (JSON Lines protocol) |
axe preview report | Capture screenshots of all #Preview blocks |
axe preview simulator | Manage simulators for preview |
Oneshot Mode (default)
axe preview MyView.swift > screenshot.png
axe preview <source-file.swift> [flags]
Builds and launches the preview, captures a PNG screenshot to stdout, then exits (exit 0 on success, exit 1 on failure).
| Flag | Description |
|---|
--preview | Select a #Preview block by title or index (e.g. --preview "Dark Mode" or --preview 1) |
--reuse-build | Skip xcodebuild and reuse previous build artifacts |
--full-thunk | Use full thunk compilation (per-file dynamic replacement) |
axe preview watch
axe preview watch MyView.swift
axe preview watch <source-file.swift> [flags]