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 or any other MCP client can see your running app, drive it, and read its performance and analytics data. Connecting takes one command.

Add the server

In your project folder, run the command for your agent:

Claude Code

Copilot

Codex

Terminal

$ squiggle init --agent claude

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

It adds Squiggle to your agent’s config and keeps every other server and setting in it. If Squiggle is already there, it changes nothing. 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.

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. --agent claude already installed it. To install or update it on its own:

Terminal

$ squiggle agent kit --install

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/, the flows are checked with squiggle agent validate, and a problem is reported straight back to your agent.
At the start of a session, squiggle doctor tells your agent what is connected before it asks.
A shell command that would erase or delete a simulator is stopped until you confirm it.

Check it works

Start your app with squiggle up, then ask your agent to call status. It reports what is connected, which app, and which tools can’t work right now and why. status needs no licence, so it also explains a licence problem.

If several apps are running, the agent attaches to the most recently launched one. Tell it which app you mean, and it switches with target.

Serve fewer tools

All 90 tools add about 36,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. 58 tools.
`analyze`	Performance and product data, without driving. 50 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.

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