# Connect your agent

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.

> **Before you start**
>
> Install the CLI and set your app up first; see [Set up your app](https://squiggle.sh/docs/setup). Connecting the server never boots a simulator, so it is safe to leave connected.

## Add the server

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

```shell
squiggle init --agent claude
```

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

```shell
squiggle init --agent copilot
```

Adds Squiggle to .vscode/mcp.json.

```shell
squiggle init --agent codex
```

Adds Squiggle to ~/.codex/config.toml.

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`:

```
{
  "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:

```shell
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.

> **Don't edit the installed files**
>
> The next install overwrites them. When the kit is out of date, `squiggle doctor` says so, and the server tells your agent once. Run `squiggle agent kit --install` again.

## 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](https://squiggle.sh/docs/agents/programs#answer-it-yourself).

## More

- [What your agent can do](https://squiggle.sh/docs/agents/tools): The tools, grouped by job, and what each group needs.
- [Intent programs](https://squiggle.sh/docs/agents/programs): One program for a whole journey, instead of a model call per tap.
- [Safety and approvals](https://squiggle.sh/docs/agents/safety): What your agent is never allowed to tap without you.
- [Benchmark an agent](https://squiggle.sh/docs/agents/benchmark): Score an agent on a fixed set of tasks.