Spiralyst Lab logo Spiralyst Lab ← All posts Developers

Blog · Developers · May 26, 2026

Drive Spiralyst Lab from Claude.

Spiralyst Lab ships a complete local automation API — every on-screen control has a programmatic twin. Here's what that means, what's exposed, and a worked example of driving it from Claude Code, Anthropic's CLI agent.

Every control, also a command

Most visual apps end at the window — what you can do is what's on screen. Spiralyst Lab keeps going. Under the hood, it's built on a simple principle: every feature you can reach with a click, you can also reach with code. That isn't a plugin bolt-on; it's how the app is designed.

Two ways into the same control surface in v3.0:

  • A local HTTP API at http://127.0.0.1:<port>/api/*. Twenty-plus endpoints across state, UI, window, audio, and export. Drive it from anything that speaks HTTP — curl, a Python or Node script, a MIDI/OSC bridge, an AI agent. The port is OS-assigned per launch — you discover it via the app log or lsof.
  • Reference Claude Code skills, published on our automation page. Four ready-to-install skill files (SKILL.md per skill) for Anthropic's Claude Code CLI agent. They call the same HTTP API — they're documentation + recipe, not a proprietary integration.

The HTTP API is the canonical surface; the skills are one example of how to wrap it for an agent. Use either, or both, or write your own.

What the API covers

The shipped endpoints are documented in full at spiralyst.com/automation.html. The short version:

  • State — read the whole scene state, set it, patch a single parameter, undo / redo, walk the undo stack.
  • UI — switch panels, scroll a control into view.
  • Window — detach the viewport into its own window (for live VJ output), reattach.
  • Audio — read a live snapshot (level, RMS, pitch, brightness, flux, multi-band spectrum), read high-rate analysis frames, read the per-band reactivity the visuals are using (with flags for "this band is maxed" or "this band isn't moving"), run Auto-Reactivity, save and apply band setups, play deterministic test tones, list audio devices.
  • Export — capture the rendered viewport straight to PNG. Exact pixels, no screen capture.

Local only — that's the trust model

The HTTP API is bound to 127.0.0.1 only. There's no remote-control surface, no public endpoint, no port-forward path to expose it. There's also no auth token — because the trust model is machine proximity. If you can reach the server, you're already on the machine. The handler that gates this lives in src-tauri/src/api/mod.rs as host_is_loopback(); it rejects any request whose origin isn't loopback.

This is consistent with the rest of Spiralyst Lab's privacy stance: no account, no telemetry, audio analyzed live and never recorded. Nothing about the API changes that — it's a local control surface for software on the same machine, full stop.

Worked example #1 — driving the app from curl

Discover the port from the app log, then drive the app from a shell:

# Discover the port (it's printed at startup in the app log)
PORT=$(lsof -nP -iTCP -sTCP:LISTEN -P -a -c Spiralyst | awk '/LISTEN/ {print $9}' | sed 's/.*://')

# Read the full scene state as JSON
curl -s http://127.0.0.1:$PORT/api/state | jq .

# Switch to a 3D Mandelbulb scene
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"patch":{"fractalType":"mandelbulb","palette":"royal-cascade"}}' \
  http://127.0.0.1:$PORT/api/state/apply

# Inspect what each band is doing right now
curl -s http://127.0.0.1:$PORT/api/audio/bands | jq .

# Capture the rendered viewport straight to PNG (exact pixels)
curl -s -X POST http://127.0.0.1:$PORT/api/export/png
sleep 0.3
curl -s http://127.0.0.1:$PORT/api/export/png    # returns the file path

The poll-and-act pattern is roughly 250 ms per tick, plenty fast for an agent that wants to read the scene + audio, decide what to do, and apply a state change once per beat or once per bar.

Worked example #2 — driving Spiralyst Lab from Claude Code

Alongside the app, we wrote four reference skills for Claude Code (Anthropic's CLI agent). To be clear about what they are: Spiralyst Lab does not bundle them, and Claude Code does not auto-install them. They are documentation files (a SKILL.md per skill) that we host on this site as worked examples of driving the HTTP API. If you want to use them, copy them into ~/.claude/skills/<name>/SKILL.md — the setup steps and the source of each file are on the automation page. You can also write your own; nothing here is proprietary to one agent.

The four reference skills, once installed:

  • /spiral-observe — read the live audio feed (snapshot, per-band reactivity, full-rate frames), read the scene state, capture a screenshot. The "eyes and ears" skill.
  • /spiral-scene — set up a scene programmatically: choose a fractal type and parameters, effects, layers, background, and wire sliders to audio bands or sine animation. Built to consume natural-language scene descriptions and translate them into /api/state/apply calls.
  • /spiral-calibrate — run the calibration suite. Plays ground-truth tones into the audio path, measures pitch accuracy, gain response, beat timing, and end-to-end render against a baseline. Grades pass/fail.
  • /spiral-heal — auto-tune reactivity (AGC). If a band's slider is pinned at the top or sitting at zero, this skill tunes gain, squelch (noise floor), and signal so the band responds cleanly to whatever's playing.

None of these skills hold any privileged binding to Claude — they're documentation + curl recipes that any agent can use. No MCP server, no proprietary integration. The point is the API contract is stable and documented; any agent that can call HTTP can drive Spiralyst Lab.

The skill in action

Assuming you've followed the setup steps to install the skill files locally and launched the app, a real transcript of /spiral-scene building a scene from a sentence, lightly edited for length:

$ claude
> /spiral-scene "six-petal rose with trails, hue reacting to the kick, slow rotation"

I'll set up a six-petal rose scene with trails enabled, the hue
parameter wired to the bass band, and a slow constant rotation. Let me:

1. Read the current state to know what I'm changing
2. Set fractal type to "rose" with petal count = 6
3. Enable trails (decay = 0.92)
4. Wire hue to the bass band's amplitude signal
5. Add a constant rotation of 0.04 rad/s

Calling /api/state/apply...
✓ Scene applied. Rendering.

Reading audio bands to confirm the kick is driving hue...
✓ Bass band is active (peak 0.74, RMS 0.31) — hue is rotating with the kick.

Done. The scene is live.

End to end: 4 seconds of agent time, one HTTP POST to /api/state/apply with a JSON patch, and the app's window shows a six-petal rose with trails on, hue rotating with the kick. If the rotation feels too fast or too slow, you tell the agent and it tweaks the parameter directly — no clicking through panels.

What you can build with it

The skills are starting points. The API enables:

  • MIDI / OSC controllers. Bridge a hardware controller to Spiralyst Lab in a few lines of code. Knobs and faders drive colors, motion, fractal parameters live. Spiralyst doesn't ship a built-in MIDI/OSC mapper — you write the bridge, the API does the rest.
  • Show-control cue stacks. Fire a scene change from a broadcast or theatre cue system — "Cue 5: phyllotaxis, brand palette, hue reacting to the kick" — as a single state push.
  • AI-driven creative pipelines. A scene that an LLM co-directs in real time: read the live audio, decide what should happen, apply it. The transcript above is the trivial version; the same loop scales.
  • Automated QA harnesses. Set a scene → render → read pixels and state → grade against a baseline → repeat. No human, no clicking. Useful if you're building reference patterns for show-control rigs.
  • Adaptive installations. A gallery piece that re-tunes itself to the room's sound over hours, or shifts its look on a schedule.
  • Measurement and research. Use the test-tone + calibration endpoints to study latency and audio-analysis accuracy, or to validate a rig before a show.

The framing question

The interesting question this raises, for us: what if more creative apps shipped this kind of surface from day one, instead of having a third-party scrape it later? A documented control contract, audited against shipped code, that an agent can drive end-to-end — versus brittle UI-scripting that breaks on every update.

Spiralyst Lab is one app, but the design pattern transfers. We made the API a first-class constraint of the codebase: every shipped feature has to ship a programmatic equivalent. The surface keeps growing with the app instead of falling behind it.

Try it

The full automation surface is documented at spiralyst.com/automation.html. If you want to drive Spiralyst Lab from your own scripts, controllers, or agents, that's the canonical reference — start there. If you're a Claude Code user and want the four reference skills, the source of each SKILL.md and the setup steps to drop them into ~/.claude/skills/ are on the same page. The skill files are short and worth reading on their own.

Spiralyst Lab is macOS 14.4+, Apple Silicon, $24.99/year, available now at spiralyst.com.

Install the Claude Code skills See the automation surface ← All posts