See what your agent did
Read every call your agent made, watch calls live, read the world's state, keep or copy a world, and delete it.
The twin records every call your agent made and what each one changed. Read it, then keep or delete the world.
Twins
Google Calendar · Gmail
You need
a world folder your agent ran in
Main command
twin world calls world
Watch out
twin api and twin world save add their own calls to the record. Read the calls first
Prerequisites
A world your agent ran in. See Run your agent.
Copy this
twin world calls world --writes # only the calls that changed something
twin world calls world --json > traces.json # every call, for your own tools
twin world save world -o after.md # the world as it stands, as a seed file
twin world delete world # done with itThe record
An agent's reply says what it thinks it did. The twin records what it actually did: every call your agent made in the world, and what each call changed. You read that record, and the world's state, from the twin CLI or the web console.
Read the calls
This prints the twin's record of every call made in the world since it was seeded, Calendar and Gmail, oldest first. The twin writes the record itself. An agent that reports a call it never made, or forgets one it did, does not change it.
Narrow it down:
--writes
only the calls that changed something
--app calendar / --app gmail
only that app's calls
--status ok
only calls that succeeded
--status error
any failure
--status 4xx
the caller's errors: denied, invalid, unknown
--status 5xx
the twin's errors
--json
JSON, for a program to read
Each call in the JSON has these fields:
app
calendar or gmail
tool
the tool called, such as events.create
status
how the call ended
at
when it was made
latency_ms
how long the twin took to answer
arguments
what your agent sent
changes
what the call changed in the world
Watch calls live
Follow the record while your agent runs, from a second terminal:
--follow first prints the calls so far, then each new one. It reads the record again every second; --interval <seconds> changes that.
In the web console, a twin's Runs page shows the same calls live, with what changed and what was refused. See Web console.
Read the world's state
twin api calls one of the world's MCP tools, as your agent would, and prints the JSON it returns:
-f key=value
an argument, as a string
-F key=value
an argument, read as JSON when it is JSON (5, true, {"a": 1})
--input file
the arguments as a JSON object, from a file (- for stdin). -f and -F add to it
--app calendar / --app gmail
the server to call. By default, the one that has the tool
--list
list the tools instead of calling one
A calendar tool that needs a calendarId gets primary when you give none. twin api exits with status 2 when the twin answers with an error.
Before and after
To see the whole world as it stands, write it as a seed file:
Put after.md beside the seed file you started from to see what your agent changed. Each call's changes in twin world calls --json shows the same, one call at a time.
Keep a world
There are two ways to keep a world. Pick by what you want to do with it.
twin world save
twin world snapshot
Gives you
a seed file
an exact copy, as JSON
Use it to
read or edit the world
make the same world again
Holds
events, other calendars and sharing, the mailbox
everything the twin holds, for every app: each event as stored, attendees' answers, labels, settings, threads
Left out
what the seed syntax cannot write, listed under # not saved
nothing
In the record of calls
yes (it reads the world as its owner)
no
Holds a token
no
no
Use a snapshot to fork a run, hand a state to a teammate, or replay a bug from the exact state it happened in. --force on save and snapshot replaces a file that already exists.
Export the calls
Write the record to a file for your own tools, dashboards or CI:
From Python, world.calls() returns the same list, and world.calls(app="gmail", writes=True, status="error") narrows it. world.follow_calls() yields each call as the twin records it, until you stop.
Hand a world to another machine
twin world handle prints the world as JSON. twin world attach picks it up on another machine, or in a later CI step, as a local folder that the other twin world commands take:
Delete the world
When you are done, delete the world and its folder:
twin world delete also takes a world's id from twin world list, for a world that has no folder, such as one twin start made:
To delete a group of worlds at once, use their label:
--label <name>
the worlds made with this label
--all
every world made on this machine, and every older t-... world your key can list (a teammate's older ones too). A teammate's newer worlds are never touched
--older-than <seconds>
only those made more than this long ago
--dry-run
list what would be deleted, and delete nothing
--yes, -y
delete without asking. Needed where there is no terminal
A folder twin world create made goes too, but only when it holds nothing but the world's own files.
A world you never delete deletes itself when its lease ends: 6 hours by default, or what you set with --lease.
Common mistakes
twin api or twin world save before you read the calls
Their calls land in the record, beside your agent's
twin world save to copy a world exactly
What the seed syntax cannot write is left out, under # not saved. Use twin world snapshot
Next
Web console: the same record, live, in your browser.
Several twins as one unit: read the calls of a whole environment.
CLI reference: every option of
twin world callsandtwin api.
Last updated: 27 October 2026
Was this helpful?