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:
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:
squiggle init --agents-onlyIn 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:
squiggle init --agent claudeAdds Squiggle to .mcp.json, and installs the kit in .claude/.
squiggle init --agent copilotAdds Squiggle to .vscode/mcp.json.
squiggle init --agent codexAdds Squiggle to ~/.codex/config.toml.
squiggle init --agent cursorAdds Squiggle to .cursor/mcp.json.
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:
{ "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:
squiggle mcp --http 7800It serves http://127.0.0.1:7800/mcp until you press Ctrl+C. Point your agent at that URL; in Claude Code:
claude mcp add --transport http squiggle http://127.0.0.1:7800/mcpEach 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:
squiggle agent kit --installThe 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:
| Skill | Used for |
|---|---|
squiggle-setup | Getting 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-drive | Making the app do something: writing intent programs, checking the result, and answering decisions. |
squiggle-perf | Making something faster: baseline, run, compare, read the findings, change, run again. |
squiggle-triage | Finding out why something failed, starting from what was recorded rather than a new run. |
squiggle-build | Building 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:
| Subagent | Job |
|---|---|
squiggle-qa | Drives a journey, checks it worked, and writes a flow you can run again. |
squiggle-perf | Runs the performance loop: run, compare, guess the cause, run again. |
squiggle-a11y | Checks labels, roles and tap-target sizes. |
squiggle-explore | Crawls the app to map its screens and find journeys. |
Four slash commands, in .claude/commands/squiggle/:
| Command | Does |
|---|---|
flow | Runs a saved flow against the connected app. |
bench | Runs a flow and compares its speed with the last benched run. |
triage | Investigates the most recent failure from what was recorded. |
legibility | Scores 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 withsquiggle 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 --quicktells 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 eraseorsimctl deleteis blocked, and your agent is told to ask you before it tries again. A command that only mentions them, such as anecho, 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:
squiggle init --pr-evidenceThat 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
.squigglefolder can be attached, such as the screenshots, filmstrips and recordings Squiggle saves there.publish_evidencewon’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:
| Mode | Serves |
|---|---|
drive | Driving the app, without performance and product data. 65 tools. |
analyze | Performance and product data, without driving. 57 tools. |
qa · perf · a11y · explore | The 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.
More
- What your agent can doThe tools, grouped by job, and what each group needs.Tools
- Intent programsOne program for a whole journey, instead of a model call per tap.Programs
- Safety and approvalsWhat your agent is never allowed to tap without you.Safety
- Benchmark an agentScore an agent on a fixed set of tasks.Benchmark