Project folder and config

For AI agents: this page is Markdown at https://squiggle.sh/docs/reference/project.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 keeps everything for a project in a .squiggle folder at the project root: your flows, your settings, and what each run records. Here is what each part holds, what to commit, and every setting in config.jsonc.

What’s in .squiggle

Pick an entry to see what it holds and whether it belongs in git. Studio, the squiggle command and the MCP server all use the same folder. In a monorepo, the project root is your app’s folder when it has its own .squiggle folder, and the repository root when it doesn’t. When the repository root has none and only one app in apps or packages has its own, that app is the project from anywhere in the repository, the root included.

  • .squiggle/

flows/

Commit it

Your flows, as YAML. This is source: commit it. When a selector heals, the fix is written here, so you review it in a diff.

What to commit

Commit flows/, interfaces/ and config.jsonc. Everything else stays on your Mac: config.local.jsonc holds this Mac’s own settings, and the rest is recorded by use and can grow to several gigabytes. squiggle init writes .squiggle/.gitignore, which ignores everything except those three and itself. You can edit it: Squiggle never rewrites it.

A .gitignore rule doesn’t apply to files git already tracks. If you committed part of the folder before, untrack it:

Terminal
git rm -r --cached .squiggle/runs

To commit more of the folder, such as a baseline you export to .squiggle/baselines with squiggle perf snapshot --export, add lines for it to .squiggle/.gitignore. Keep baselines/first.json ignored: it marks that this Mac took its first baseline, and committed, it stops everyone else’s from being taken.

.squiggle/.gitignore
!baselines/!baselines/**baselines/first.json

squiggle doctor warns, on its store in git line, about files git tracks that this file ignores, and names both fixes: untrack them, or add them here if you commit them on purpose.

When Squiggle adds the folder

The squiggle command and the MCP server add a .squiggle folder to a project only when you set the project up with squiggle init or squiggle add, or save a flow to a path you name with squiggle flow --from-recording <file> -o <path>. Before that, they write nothing into it, not even a .gitignore. An agent can start the MCP server in any repository, and you can drive and watch an app from there, but nothing is saved. Studio writes only into a project you opened in it.

A project is set up once its .squiggle folder holds config.jsonc, flows/ or interfaces/. A .squiggle folder with only a .gitignore and recorded data, like the one older versions left in any repository you ran a command in, doesn’t count: Squiggle adds nothing more to it, and you can delete it.

Declare a screen’s interface

Before you build a screen, you can write down the controls it will have, one file per screen in .squiggle/interfaces/. The report card then checks the built screen against it, and squiggle agent validate accepts a flow that targets the declared controls before the screen exists.

.squiggle/interfaces/settings.json
{  "route": "settings",  "path": "/settings",  "controls": [    { "testID": "settings-save", "role": "button", "leadsTo": "back" },    { "testID": "settings-delete-account", "role": "button", "destructive": true }  ]}
KeyWhat it holds
routeThe screen’s full route, the name status and the Screen map show: settings for app/settings.tsx, (tabs)/explore for app/(tabs)/explore.tsx. Its last segment alone, such as explore, works too, except index, which names only your home screen.
pathThe path that opens it, when it differs from the route.
controls[].testIDRequired. The testID the control renders with.
controls[].roleIts accessibilityRole: button, link, switch, textbox and so on.
controls[].labelIts accessibility label.
controls[].leadsToThe route a press opens, or back for a control that returns to the screen before.
controls[].destructivetrue for a control that does something irreversible. Mark it in your code with agentHint({ destructive: true }) too.

The card fails a row for a declared control the screen doesn’t render, a testID it renders that isn’t declared, a control that opens a different screen, and a different role. A file that isn’t JSON, has no route, or has a control with no testID fails a row too.

How Squiggle finds the folder

The squiggle command and the MCP server use the project root. Starting where you run them, they first look for the repository root: the nearest folder with a lockfile (bun.lock, bun.lockb, yarn.lock, package-lock.json or pnpm-workspace.yaml) or a package.json that declares workspaces; else the nearest folder with .git; else the nearest folder that already holds .squiggle. The project root is then the nearest folder, from where you are up to that root, whose .squiggle holds a config.jsonc, a flows folder or an interfaces folder. If none does, and exactly one folder in the repository root’s apps or packages folder has such a .squiggle, that app is the project; otherwise it is the repository root. So in a monorepo whose app keeps apps/mobile/.squiggle/config.jsonc, a command run at the repository root, in apps/mobile or in packages/ui uses that folder, and so does a coding agent or CI job started at the root. With two such apps, run commands in the app’s folder. A .squiggle folder holding only what runs recorded doesn’t count. Set SQUIGGLE_PROJECT_ROOT to name the root yourself. Studio finds the project the same way from the folder you open in it.

Paths in config.jsonc, such as flowsDir, are relative to the project root. Commands that read your app’s source (the testID check in squiggle agent validate, affected_by_diff, squiggle crawl --changed) also read the src, app and components folders of every package in the repository’s apps and packages, so a component shared from packages/ui/src counts. Paths you give --files on squiggle card and squiggle crawl are relative to the project root too.

config.jsonc

Settings for everyone who works on the project. Comments are allowed. Your own settings, such as updateChannel, live in ~/.squiggle/config.jsonc, and the project’s file wins over it for a key both set. Settings for this project on this Mac only go in config.local.jsonc, which wins over both; see Settings for this Mac only. Environment variables such as SQUIGGLE_PORT, and flags on the command line, override them all for one run. squiggle doctor prints each resolved value and where it came from.

A running MCP server picks up an edit to config.jsonc or config.local.jsonc on its next tool call: a change to the app (apps or bundleId), the udid, the port or the approvals block reconnects it to the app as the files now say, and that tool result tells your agent what changed. Two changes need a restart of the server: watch.push turning channel on or off, and the port in a Niteshift task. status and the tool result after the edit say so when the file and the server disagree.

.squiggle/config.jsonc
{  // the app under test, when this repo has one  "bundleId": "com.acme.shop",  "shards": 4,  // --profile ci applies profiles.ci on top of the settings above  "profiles": {    "ci": { "relay": false, "shards": 2 }  }}
KeyWhat it sets
bundleIdThe app under test, when the project has one. Squiggle saves data only from the apps this project names here or in apps.
budgetsPerformance limits per screen, keyed by the screen’s full route, with "*" for every screen. squiggle init writes a default set. See Set a budget per screen. A screen’s sizes say how big it must get without dropping frames; see Keep a screen off its cliff.
appsThe app under test on each platform, for a project that builds more than one, for example { "ios": "com.acme.shop", "macos": "com.acme.shop.mac" }. web takes a React web app’s origin, such as "http://localhost:5173", so the iOS app’s flows run on it and its data is saved here; see React web apps. The platform picks which; bundleId is the fallback. squiggle init fills it in from your ios/ and macos/ projects. Only these apps (and a development build made inside the project) are saved into this project: another app that connects is driven live and saved nowhere. Every git worktree of a project declares the same apps. A Squiggle server started in the main checkout saves a development build into the worktree it was built in: your agent’s screenshots, screen recordings, flows and screen memory for it go there, even when SQUIGGLE_PROJECT_ROOT names the main checkout. A Squiggle server started in a worktree always works in that worktree, even when the app comes from the main checkout’s Metro. Remove a worktree while a server or Studio is still running and nothing more is saved for its app: status says the project is gone, and the worktree folder is not created again.
navigationWhat should hold for every screen of each app, per platform like apps: home, launch, terminals, back, gates and deepLinks. squiggle contracts navigation checks it. See Check your app’s navigation.
platformios, macos or web, the platform commands use when you don’t pass --platform. squiggle init sets macos for a macOS app with no ios/ folder.
deviceprovider: local (the default, a simulator or Mac this machine runs) or niteshift, for a Niteshift task’s simulator. SQUIGGLE_DEVICE_PROVIDER overrides it. See Niteshift tasks.
webHow Squiggle opens a React web app in its window: url (the address it opens when nothing else names one), browser (chrome, chromium, edge or a path), channel (stable, beta, dev or canary), viewport (width and height in CSS pixels, and mobile: true for touch input) and permissions (each granted, denied or prompt). See Choose the browser and the screen.
releasetrue keeps Squiggle in release builds of your app: the SDK, the Babel plugin’s output and the native library. Off by default, so a release build has none of it. See What ships in your release build on the setup page.
flowsDirThe folder squiggle watch watches for flow changes, if not .squiggle/flows. Your flows stay in .squiggle/flows: every command, Studio and your agent read them there.
shardsHow many simulators squiggle flows uses at once. --shards overrides it.
udidThe simulator to use when several are running. A UDID differs from Mac to Mac, so set it in config.local.jsonc (see Settings for this Mac only). With none named (here, by --udid or by SQUIGGLE_UDID), a command that drives a device skips any simulator whose app a session of another project or checkout drives, then takes the one left; of several, the one a Squiggle session of this project or Studio drives, else the one running this project’s app. When that still leaves more than one, it stops and lists them with the sessions on each; when every booted simulator is held, it stops and says who holds each. squiggle flows runs only on this simulator; pass --udid (repeat it for more) to name others.
portThe port squiggle waits on for the app (default 7777). SQUIGGLE_PORT overrides it for one shell. Every command that talks to the app honours both, and an app Squiggle launches is pointed at that port. Otherwise the app must connect to the same port: set EXPO_PUBLIC_SQUIGGLE_WS_URL=ws://localhost:<port> in its .env. When you work on two projects at once, give each its own port: on a shared port, the first session to start also receives the other project’s app (it leaves that app alone, and the app’s own project still drives it).
metroUrlThe Metro server that serves your app, for example Metro on port 8082: "http://localhost:8082". Without it, Squiggle uses the server your app’s bundle came from, or else the server that serves your app, on any port. Profiles, heap snapshots, squiggle probe and symbolicated stacks need this server, and a relaunch puts your development build back on it. The CLI, the MCP server and Studio all read it, and use the server you name without asking it which app it serves, so set it when Squiggle doesn’t find your server or your server is slow to answer. SQUIGGLE_METRO_URL overrides it for one shell.
relayConnect through Studio instead of directly, so Studio keeps showing the app during a run.
relayUrlThe address to connect through. Setting it turns relay on.
profilesNamed sets of the settings above. --profile ci applies profiles.ci on top.
telemetryfalse turns off anonymous usage events for everyone who works on this project. true has no effect here: whether they are on is each person’s own setting (squiggle telemetry).
crashReportsfalse turns off crash reports for everyone who works on this project. true has no effect here.
prEvidencetrue lets your agent attach a recording or screenshot to a pull request on its own. Off by default; squiggle init --pr-evidence turns it on, and squiggle flow --attach-pr never needs it.
approvalsWhat happens when your agent reaches a control the deny rail blocks: mode (ask, the default; agent; or auto), environment (development, staging or production; with none declared, and for any release build, it is production), allow and deny (lists of testIDs, labels or texts). SQUIGGLE_APPROVALS overrides mode for one process, and SQUIGGLE_ENVIRONMENT declares the environment too. See Let your agent approve while you develop.
watchWhat your agent’s Squiggle server does when the app breaks: enabled (default true; false, or SQUIGGLE_WATCH=0 for one process, also stops it recording the app, so its perf_sql and perf_report read only what Studio or a squiggle flow run recorded), push (notice, the default; channel, which also pushes each incident to Claude Code where channels are on; or none), capture (record each incident, default true), profile (local, or ephemeral for a throwaway sandbox), budget, and mute (performance findings kept off your agent’s tool results, by detector, component or both; still recorded). See Set what your agent keeps.
leaderboardtrue lets a benchmark score be published to the public leaderboard. Off by default.
updateChannelThe release channel squiggle update follows. squiggle update --channel sets it.

Settings for this Mac only

Put settings that differ from one Mac to another in .squiggle/config.local.jsonc, beside config.jsonc. It takes the same keys. A key you set there replaces the same key in config.jsonc, as a whole: an apps block there replaces the shared one rather than adding to it. Profiles, environment variables and flags still override it. The file stays out of git, because .squiggle/.gitignore ignores everything it doesn’t list. The squiggle command, the MCP server and Studio all read it.

.squiggle/config.local.jsonc
{  // the simulator squiggle init made for this project on this Mac  "udid": "4F2A9C1E-7B3D-4E8A-9C21-5D6F0A1B2C3D",  "port": 7787}

squiggle init writes udid here when it creates a simulator for the project. See Give the project a simulator of its own. release is the exception: your app’s build reads it from config.jsonc only.

Telemetry

Squiggle sends anonymous usage events, never before it has shown you a one-time notice. To see exactly what is sent, run squiggle telemetry. To turn it off, run squiggle telemetry off, or set DO_NOT_TRACK=1 or SQUIGGLE_TELEMETRY=0.