Spectra
Content capture for marketing — screenshots, videos, and app usage sequences for blog posts, social media, and documentation.
Works across web (Chrome DevTools Protocol), macOS (accessibility bridge), iOS and watchOS (simulators).
Install
Via Claude Code plugin marketplace (recommended)
/plugin marketplace add tyroneross/spectra
/plugin install spectra@spectra
Manual install (development / library use)
Requirements: Node.js 22+, macOS (for native features), Xcode CLI tools (for Swift compilation)
git clone https://github.com/tyroneross/spectra.git
cd spectra
npm install
npm run build
Native bridge (macOS/iOS/watchOS automation)
# Compile the Swift binary to ~/.spectra/bin/spectra-native
npm run build:native
# Optional: compile the SwiftUI test fixture
npm run build:test-app
macOS permissions required:
- System Settings → Privacy & Security → Accessibility — add your terminal app
- System Settings → Privacy & Security → Screen Recording — add your terminal app (for video capture)
Dashboard (web UI)
cd web-ui
npm install
cd ..
npm run serve # → http://localhost:4300
Claude Code Plugin
Spectra is a Claude Code plugin. Install via the marketplace (see above) or locally for development:
# From another project, point Claude Code at the Spectra directory
claude --plugin-dir /path/to/spectra
Or add to .claude/settings.json:
{
"plugins": ["/path/to/spectra"]
}
Slash Commands
| Command | Purpose |
|---|
/spectra:connect <target> | Start a capture session |
/spectra:walk <description> | Walk through a flow with natural language |
/spectra:capture | Screenshot current state |
/spectra:sessions | List active sessions |
Routing: Host-Routed vs Standalone
The primary Spectra path is host-routed. A host agent such as Claude Code,
Codex, or another LLM coding host reads spectra_snapshot, plans the next
action, and calls Spectra MCP tools to execute and capture. Spectra does not
need a model API key for this path.
The standalone Spectra.app fallback is for sessions launched outside a host
agent. In that case the app uses WalkthroughPlanner.swift and
AnthropicClient.swift to plan locally, with the user's key stored in Keychain.
Use host-routed walkthroughs when working inside a coding agent. Use the
standalone path when the menu-bar app is the only planner available.
MCP Tools
spectra_connect
Start a new UI automation session.
| Param | Type | Required | Description |
|---|
target | string | yes | URL, app name, or sim:device identifier |
name | string | | Human-readable session name |
record | boolean | | Start video recording immediately |
Examples:
target: "https://myapp.vercel.app" → web (CDP)
target: "Finder" → macOS native (AX)
target: "sim:iPhone 16 Pro" → iOS simulator
target: "sim:Apple Watch Series 10" → watchOS simulator
Returns: { sessionId, platform, target, name }
spectra_snapshot
Get the current accessibility tree snapshot.
| Param | Type | Required | Description |
|---|
sessionId | string | yes | Active session ID |
screenshot | boolean | | Include base64 screenshot |
Returns: Serialized AX tree — compact element list with roles, labels, bounds, actions.
spectra_act
Perform an action on a specific element.
| Param | Type | Required | Description |
|---|
sessionId | string | yes | Active session ID |
elementId | string | yes | Element ID from snapshot (e.g., "e4") |
action | enum | yes | click, type, clear, select, scroll, hover, focus |
value | string | | Text to type or scroll amount in px |
Returns: { success, snapshot } — updated snapshot after the action.
spectra_step
Natural language navigation — describe what to do, Spectra finds the element and executes.
| Param | Type | Required | Description |
|---|
sessionId | string | yes | Active session ID |
intent | string | yes | What to do, e.g., "click the Log In button" |
Returns: { resolved, elementId, action, confidence, snapshot } — plus optional screenshot.
Uses the Jaro-Winkler resolution engine to fuzzy-match intents to AX tree elements.
spectra_capture
Take a screenshot or manage video recording. Supports intelligent framing modes.
