Connect your agent

For AI agents: this page is Markdown at https://squiggle.sh/docs/agents.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.

Squiggle is an MCP server, so Claude Code, Copilot, Codex, Cursor or any other MCP client can see your running app, drive it, and read its performance and analytics data. squiggle init connects the agents it finds.

Add the server

squiggle init looks for Claude Code, Copilot (VS Code), Codex and Cursor on your Mac and asks once:

Listing
Register Squiggle with Claude Code and Codex?

Yes is selected, so press Enter to add Squiggle to each one. To connect your agents without setting up an app, run this in your project folder:

Terminal
squiggle init --agents-only

In Studio, open Settings and click Connect your agents. It does the same for the open project and shows which agents it connected.

Squiggle never adds itself to an agent without that yes. With no terminal to ask in, such as in CI or a script, init names the agents it found and connects none; add --yes to connect them all. --agent none connects none and stops the question.

To connect one agent by name, pass it:

Terminal
squiggle init --agent claude

Adds Squiggle to .mcp.json, and installs the kit in .claude/.

Squiggle keeps every other server and setting in those files. If Squiggle is already there, under any name, or for Claude Code in a .mcp.json higher up in the repository or in ~/.claude.json, it changes nothing, so you can run it again safely.

The files in your project start Squiggle as squiggle, so they work on every teammate’s machine. Your agent needs to find that command: if your terminal can’t, init says so. Studio installs it in ~/.local/bin, which macOS does not add to your PATH; in Studio, open Settings and click Add to PATH next to Command line. Codex’s config is yours alone, so when your terminal can’t find squiggle, it gets the full path instead.

To add it by hand, use your client’s command, for example claude mcp add squiggle -- squiggle mcp, or put this in .mcp.json:

.mcp.json
{  "mcpServers": {    "squiggle": {      "command": "squiggle",      "args": ["mcp"]    }  }}

Restart your agent client so it picks the server up.

Serve MCP over HTTP, for an agent that is already running

The steps above have your agent start Squiggle itself. If it is already running, or can only reach MCP servers by URL, start the server yourself from your project folder:

Terminal
squiggle mcp --http 7800

It serves http://127.0.0.1:7800/mcp until you press Ctrl+C. Point your agent at that URL; in Claude Code:

Terminal
claude mcp add --transport http squiggle http://127.0.0.1:7800/mcp

Each agent that connects gets its own session, as if it had started its own server. The session ends when the agent closes it, or after 30 minutes with no request and no tool call running. After that, the agent has to reconnect.

Keep the port outside 7777 to 7799, which Squiggle uses to reach your app. If the port is taken, the command stops and says so. Pick another, or use --http 0 to take a free one; the address it serves is printed when it starts.

Add the kit

The tools say what they do. The kit says how to use them well: when to write a program instead of tapping, how to read a finding, how to check a setup. Connecting Claude Code already installed it. To install or update it on its own:

Terminal
squiggle agent kit --install

The kit alone doesn’t connect Claude Code to Squiggle. When nothing registers the server for this folder, the command says so and names squiggle init --agents-only --agent claude, which does.

Five skills, in .claude/skills/. Your agent loads one when the task matches:

SkillUsed for
squiggle-setupGetting the simulator, the app and Squiggle ready, and proving it. Read first when a flow fails in a way that might be the environment, not your code.
squiggle-driveMaking the app do something: writing intent programs, checking the result, and answering decisions.
squiggle-perfMaking something faster: baseline, run, compare, read the findings, change, run again.
squiggle-triageFinding out why something failed, starting from what was recorded rather than a new run.
squiggle-buildBuilding a feature: declare its handles and budgets, write the flow first, build it, then fix every row of the report card until it is green. When two ways to build it are both plausible, it builds each on a branch and keeps the one squiggle bakeoff measures better.

Four subagents, in .claude/agents/. Each can use only the tools its job needs:

SubagentJob
squiggle-qaDrives a journey, checks it worked, and writes a flow you can run again.
squiggle-perfRuns the performance loop: run, compare, guess the cause, run again.
squiggle-a11yChecks labels, roles and tap-target sizes.
squiggle-exploreCrawls the app to map its screens and find journeys.

Four slash commands, in .claude/commands/squiggle/:

CommandDoes
flowRuns a saved flow against the connected app.
benchRuns a flow and compares its speed with the last benched run.
triageInvestigates the most recent failure from what was recorded.
legibilityScores how easily an agent can drive the app, and fixes the top findings.

Clients other than Claude Code can read each skill from the server as a squiggle://skill/… resource.

Hooks, if you want them

--install leaves the hooks out, because adding them edits your settings.json. Run squiggle agent kit -o ./kit to read them first. There are three:

  • After your agent edits a file in .squiggle/flows/, that file is checked with squiggle agent validate, against the project whose .squiggle/ holds it, so it works from a monorepo root whose app keeps its own .squiggle/. A flow that would not run, or that targets a testID nothing in your source can render, is reported straight back to your agent. If the check itself can’t run (the squiggle command isn’t found, say), you see a warning and the edit stays as it is.
  • At the start of a session, squiggle doctor --quick tells your agent, in a second or two, which simulator it would use, whether your app is running with Squiggle’s agent, who else holds the device, whether your installed SDK and kit match the CLI, whether you have a licence, and the one step to take next. It doesn’t wait for your app, so a session in a project whose app isn’t running starts straight away. The session starts whatever it finds.
  • A shell command that runs simctl erase or simctl delete is blocked, and your agent is told to ask you before it tries again. A command that only mentions them, such as an echo, a commit message or a search, runs as usual.

Check it works

Ask your agent to call status. Your agent’s tools launch your app when they need it: an iOS app on the simulator, your macOS app, or your React web app in Squiggle’s window (see React web apps). status reports what is connected, which app, and which tools can’t work right now and why. status needs no licence. If a tool refuses for a licence, its message says what to do, and the squiggle://license resource shows the licence.

After you update Squiggle, restart the MCP server so its tools match the new version. Until you do, status reports the running and installed versions under server, with a restart line, and the next tool result after the update carries a notice once, such as This MCP server is Squiggle 0.6.6, the installed CLI is 0.6.7: restart the MCP server so its tools are 0.6.7.

When your project’s iOS app is installed but not running (you stopped it, or it crashed), the first tool that needs it, such as describe or tap, launches it on the simulator your agent drives, and that tool’s result says it did. The app starts on its first screen. Your agent launches only the app your project declares, and never on a simulator that another Squiggle session is using: there it waits for the app, and launch_app starts it.

If several apps are running, the agent attaches to your project’s app, and when more than one is up (another checkout of this repository runs the same app), it prefers the one your project’s own Metro serves, else the most recently launched one. From then on it stays on that simulator until you tell it to switch with target: your app launched on another simulator, by another checkout or another Squiggle session, doesn’t move it. When the app it drives stops or crashes, the agent stays on that simulator and launches the app there again. It moves on its own only when that simulator is shut down, and the next tool result says where it went. With several simulators booted and none running your app, the tools that drive a device use the simulator that Studio or another Squiggle session of this project is driving. When your project declares its app, only the simulators that have it installed count, so a single one is used without asking. Otherwise they refuse to guess and list the simulators; the agent picks one with target.

Your agent never takes an app that another Squiggle session is driving: a CLI run or another agent’s server for a different project, or for another checkout of this repository, which declares the same app. That app is listed under others in status with heldBy naming the session and its port, and the agent picks another simulator. An app of another project is never named to your agent: it is listed as app: "an app this project doesn't own" with owned: false, a Mac app or browser tab of another project has no target to switch to, and the heldBy line naming the session that holds it calls the app the same way. Another checkout of this repository runs your own app, so it is still named. When no other simulator is booted, the first tool says so, names the session, and tells the agent to create a simulator of its own with the device tool’s simulator argument (or boot one that is shut down) and pick it with target or SQUIGGLE_UDID. target refuses to switch to that app, launch_app and run_flow with fresh refuse to relaunch it, and an agent pinned to that simulator stops when it connects, with a message naming the session. An idle agent server never asks another checkout’s app to connect to it either. Studio and other sessions of this same project share the app with your agent.

Hear when the app breaks

From the moment your agent’s Squiggle server starts, it watches your app, without getting in the way of Studio or a run. When the app crashes, throws, stalls or spikes, or a performance finding appears (a render storm, a memo miss, a long JS task), the agent’s next tool result says so, and incidents lists what happened with a recording of the seconds before it. The agent can replay the recording and fix the bug before it moves on. Turn it off, or set what it keeps, with the watch block of your config; see Set what your agent keeps.

Show your work on the pull request

When your agent changes what your app looks like, it can put a screenshot, a filmstrip (one image of a whole journey) or a short recording on the pull request, so you can see the result without running the branch. It stays off until you turn it on, because it posts pictures of your app where your collaborators can see them:

Terminal
squiggle init --pr-evidence

That adds "prEvidence": true to .squiggle/config.jsonc. Set it to false to turn it off again.

  • On a pull request you opened, the evidence goes in the description, in a block of its own; the rest of the description is never changed. On someone else’s pull request it goes in a comment.
  • Each round replaces the one before, so ten rounds of changes leave one set of pictures.
  • Squiggle posts with your GitHub CLI login (gh auth login), and you need write access to the repository.
  • PNG, JPEG, GIF, WebP, SVG, MP4, MOV and WebM files work. Each can be up to 10 MB on a free plan, about 30 seconds of recording, and a video up to 100 MB on a paid plan.
  • Only files in your project’s .squiggle folder can be attached, such as the screenshots, filmstrips and recordings Squiggle saves there. publish_evidence won’t post any other file from your machine.
  • If an upload fails, your agent tells you why and gives you the file’s path, so you can attach it yourself.

From a terminal, squiggle flow checkout --record --attach-pr records a flow and attaches the video. That needs no setting: typing the flag is your go-ahead.

Run it in a Niteshift task

The server also runs in a Niteshift task’s Linux sandbox, where the task’s agent drives your iOS app on the simulator Niteshift provides. Squiggle drives the app from inside it, and returns steps outside the app, such as a launch, for the task’s agent to take. Nothing is posted to the pull request from there. See Niteshift tasks.

Serve fewer tools

All 97 tools add about 54,000 tokens to every conversation. Set SQUIGGLE_MCP_MODE in the server’s environment to serve fewer:

ModeServes
driveDriving the app, without performance and product data. 65 tools.
analyzePerformance and product data, without driving. 57 tools.
qa · perf · a11y · exploreThe 14 to 19 tools the matching subagent uses.

Leave it unset to serve everything. A value it doesn’t know also serves everything, and says so.

Give your agent these docs

Every docs page has a plain Markdown copy at its address plus .md, such as squiggle.sh/docs/flows.md, so an agent can read it without the page around it. Under each page’s title, Copy as Markdown copies it to paste into a chat. squiggle.sh/llms.txt lists every page’s copy, and squiggle.sh/llms-full.txt is all of them in one file.

See what your agent saved, in Studio

A program your agent saves with library_save, and a flow with an agent: step, appear on the Agentic tab of Studio’s Flows screen. Run one from there to watch it on the simulator, and answer any decision it stops on yourself; see Answer it yourself.

Loading the live Studio…
An agentic flow and its recorded steps. Live, in your browser.Open in Studio

Agentic flowsStudio tour · 9 steps

More