Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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 it

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

Option
Shows

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

Field
What it is

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

What is in the record, and what is not.

  • Reading the record (twin world calls) is not a call. It never shows up in the record.

  • The seed's own calls, and those of twin world trigger, are left out. They made the world; they are not your agent's.

  • twin api and twin world save read the world as its owner. Their calls do show up, beside your agent's. Read the calls first if you want a record of your agent alone.

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:

Option
What it does

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

Option
What it does

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

If the twin could not delete a world, its folder is kept. Run twin world delete again. It exits with 69 when the twin is down, and 2 otherwise.

Common mistakes

What you write
What happens

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


Last updated: 27 October 2026

Was this helpful?