Tasks and runs

### From your coding agent

One command gives Claude Code, Codex or Cursor two StateWeave skills. From then on you ask in plain words, and your coding agent connects your agent to fresh copies of its apps, runs it, writes and uploads tasks, and finds why a run failed. It works through sw , the same commands you would run.

### Set it up

Make an API key in your workspace (the key icon at the bottom of the left rail, Connect your agent ), then, in a terminal:

Shell

pip

install

-U

stateweave-sdk

sw

login

--url

https://acme.app.stateweave.net

--key

sw\_…

sw

setup

sw login keeps your workspace's address and key (see Quickstart ). sw setup copies the skills to every coding agent it finds on this machine, without asking, and says what it did. For Claude Code it also adds \*.app.stateweave.net to sandbox.network.allowedDomains in ~/.claude/settings.json , so sw and your agent can reach your workspace from inside Claude Code's sandbox, and prints a line saying so. Start a new session of your coding agent afterwards so it loads them. Your key stays in sw 's own settings, never in the coding agents' files.

| Coding agent | Skills |
| --- | --- |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.agents/skills/ |
| Cursor | ~/.agents/skills/ |

Options

sw

setup

--client

cursor

\# only one of them: claude-code, codex, cursor or all

sw

setup

--project

\# into this project's .claude/skills and .agents/skills, to commit for your team

sw

setup

--remove

\# take the skills out again, nothing else

Codex and Cursor sandbox their commands' network too, with settings of their own: allow \*.app.stateweave.net there if they can't reach your workspace.

Before version 0.6, sw mcp install added an MCP server of StateWeave's own. sw setup takes that server out of Claude Code, Codex and Cursor, with the older skills, and leaves anything it didn't add.

### Ask in plain words

Open your agent's project in the coding agent and say what you want. For example:

Prompts

Set up StateWeave for my agent Write three StateWeave tasks for what my agent does, one with a Slack outage, and upload them My agent posts duplicate Slack messages when it handles refunds: reproduce it on StateWeave and fix it Run my StateWeave tasks and tell me whether this change made anything worse

Your coding agent doesn't stop to ask. It takes sensible defaults, such as reusing a sandbox whose apps fit, and says what it chose in its report, with a link to every run's page. Your coding agent's own permission prompts still apply to the files it edits and the commands it runs. It stops only when sw has no address or key, where it tells you to run sw login , or when your agent needs a secret of its own that isn't on the machine.

### The two skills

| Skill | What your coding agent does with it |
| --- | --- |
| stateweave-setup | Connects your agent. It reads your code to find the apps your agent uses and how it reaches them, uses your workspace's Starter sandbox (writing a few records into it through the apps' APIs when your agent needs something to work on), and writes stateweave-agent.sh , which maps the run's variables onto the names your code already reads. It runs your agent once on fresh copies to prove the calls reach StateWeave, then runs the tasks already in your workspace or your project. |
| stateweave-use | Everything after that. It makes and fills sandboxes and keeps versions. It writes tasks in Harbor's layout, with checks through the apps' public APIs, answer formats, personas and injected faults , proves them and uploads them. It runs your agent on them, reads a failed run's whole record, finds the first step that went wrong and fixes your code. |

### What it runs

Nothing your coding agent does needs anything you couldn't do yourself. These are the commands the skills use:

Shell

sw

sandbox ls

\# the Starter sandbox, or another (sw sandbox new, generate)

sw

run p-7d21c4

--apps

slack,zendesk

--agent

my-agent@dev

--prompt

"Summarize my open tickets"

-- ./stateweave-agent.sh

\# fresh copies of the sandbox's apps, your agent on them, then they stop

sw

run p-7d21c4

--agent

my-agent@dev

--prompt

"$(cat refund-digest/instruction.md)"

--checks

refund-digest \\ -- ./stateweave-agent.sh

\# the same, judged by a task's checks before it is uploaded

sw

task import refund-digest

--check

\# prove the task; nothing is kept

sw

task import refund-digest

\# keep it as a test

sw

run t-4f2a9c

--agent

my-agent@0.3 -- ./stateweave-agent.sh

\# a graded run of the test

sw

trace r-ef8604ff

\# the run's whole record, into .stateweave/runs/r-ef8604ff/

sw run p-… is a twin run : fresh copies with no test, not graded and without faults, stopped when the command exits. sw trace writes trace.jsonl (every call your agent made, whole), changes.json (how many records changed in each app), task.json , faults.json and, when your agent's transcript was handed in, transcript.\* . The folder has its own .gitignore , so none of it is committed. See sw command line for every option.

The apps' MCP servers are another thing. Slack, Gmail, Salesforce, Shopify, WhatsApp, Microsoft Teams, Stripe, HubSpot and GitHub serve their vendors' MCP servers, for the agent you are testing: see MCP servers . StateWeave itself no longer has an MCP server for coding agents.

### Limits

Each API key may have 3 twin runs going at once. sw run p-… stops its own when the command exits.

A twin run lasts an hour unless opened for longer ( --timeout ), up to 24 hours.

A transcript may be 20 MB.

[Starter sandbox](https://stateweave.net/docs/sandboxes#the-starter-sandbox)

[injected faults](https://stateweave.net/docs/faults)

[Quickstart](https://stateweave.net/docs/quickstart)

[twin run](https://stateweave.net/docs/run#twin-runs)

[sw command line](https://stateweave.net/docs/cli)

[MCP servers](https://stateweave.net/docs/mcp)