axe

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]