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:
pip install -U stateweave-sdk
sw login --url https://acme.app.stateweave.net --key sw_…
sw setupsw 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/ |
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 elseCodex 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:
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 worseYour 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:
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.