> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/twins/using-twins/describe-a-world.md). # Describe a world Write a seed file that says what is on the calendar and in the mailbox when a world starts. Write a seed file; `twin world create` turns it into a private world with exactly that data in it. | | | | ------------- | ---------------------------------------------------------------------------- | | **Twins** | Google Calendar ยท Gmail | | **You write** | a seed file (`seed.md`): a `## Setup` section and one World section per twin | | **You get** | a private world, from `twin world create seed.md --folder world` | | **Watch out** | the clock pins a weekday, not a date. Name days as weekdays (`Thu`, `Thu+1`) | ## Prerequisites * The `twin` CLI. See [Quickstart](/twins/getting-started/quickstart.md). * A sign-in: run `twin login`, or set `TWINS_API_KEY`. See [Keys and limits](/twins/reference/keys-and-limits.md). ## Copy this A complete seed file, with a calendar and a mailbox: ```markdown ## Setup twin: calendar, gmail now: Mon 09:00 ## World: calendar every weekday 10:00-10:30 Standup Wed 15:00-16:00 Dentist Thu 09:00-09:30 Team sync (priya@acme.test) ## World: gmail Fri 16:42 Priya Shah -> me "Call on Thursday" #priya-call // Could we find an hour on {Thu}, any time between 2pm and 4pm? ``` Make the world from it: ```bash twin world create seed.md --folder world ``` The rest of this page covers each part. {% hint style="info" %} `twin --list` shows the twins you can use, and the World section that seeds each one. {% endhint %} ## Setup `## Setup` holds settings, one `key: value` per line. | Setting | What it does | Example | | ------- | ---------------------------------------------------------------------------------------------------------- | ----------------------- | | `twin:` | names the twins the file uses. It is for people reading the file: the World sections decide what is seeded | `twin: calendar, gmail` | | `now:` | pins the world's clock to a weekday and time | `now: Mon 09:00` | ## The world's clock `now: Mon 09:00` pins the world's "now". Every day in the file is read against it, so "Thursday" always means the same day, whenever you make the world. * On the **calendar**, `Wed` is the coming Wednesday after the clock, never the same day. `Wed+1` is the Wednesday a week later. * In the **mailbox**, `Fri` is the most recent Friday before the clock. `Fri-1` is the Friday a week before that. `today 08:30` is the clock's own day. * Times are UTC. Write two-digit hours: `09:00`, not `9:00`. When you run an agent with `twin world run`, it gets the world's "now" in `TWIN_NOW` (for example `2026-09-28T09:00:00Z`). Have your agent read it, so its "today" matches the world's. See [Run your agent](/twins/using-twins/run-your-agent.md#the-worlds-clock). {% hint style="warning" %} The clock pins a weekday, not a date. Name days as weekdays (`Thu`, `Thu+1`), never as calendar dates. {% endhint %} ## World: calendar `## World: calendar` lists the calendar before your agent starts, one event per line. ``` Wed 10:00-11:00 Q4 planning sync (riley@acme.test) Thu 09:00-09:30 1:1 (manager@acme.test, riley@acme.test) private Tue+1 14:00-15:00 Board prep // Agenda: Q3 numbers, hiring plan Wed 10:00-11:00 Design review (sam@acme.test declined, mira@acme.test accepted) [location: Board room; tentative] Thu all day Offsite Fri 14:00-16:00 Deep work [focus time] ``` | Part | What it means | Example | | ------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- | | day and time | the day (against the clock) and the start and end, in UTC | `Wed 10:00-11:00` | | `all day` | an all-day event, in place of the times | the `Offsite` line above | | title | the event's title, after two spaces | `Q4 planning sync` | | `(...)` | attendees. A reply after an address sets it: `accepted`, `declined`, `tentative`, `invited` (no reply yet) | `(sam@acme.test declined)` | | `private` | at the end of the line, after two spaces: a private event | the `1:1` line above | | `[...]` | details, separated by `;` (see below) | `[location: Board room; tentative]` | | `// text` | the event's description. Your agent only sees it by opening the event | `// Agenda: Q3 numbers` | The details in `[...]` can be: | Detail | What it does | | ---------------------- | ------------------------------------------------------------------------------------------------------ | | `location: Board room` | sets the location | | `tentative` | marks the event tentative | | `free` | shows the time as free | | `color: Tomato` | one of Lavender, Sage, Grape, Flamingo, Banana, Tangerine, Peacock, Graphite, Blueberry, Basil, Tomato | | `reminder: 10` | a reminder, in minutes before | | `focus time` | a focus-time block (needs times, not `all day`) | | `out of office` | an out-of-office block (needs times, not `all day`) | In a file with only a calendar, plain `## World` means the calendar. When the file also has a mailbox, name each section: `## World: calendar` and `## World: gmail`. ### Recurring events Start a line with `every` to make a recurring event: ``` every Mon 09:00-09:15 Standup every weekday 08:30-08:45 Inbox zero every day 18:00-18:15 Daily wrap-up ``` | Rule | Repeats | | ------------------------- | ------------------- | | `every Mon` (any weekday) | weekly, on that day | | `every weekday` | Monday to Friday | | `every day` | daily | The series starts on the next such day after the clock. ### Other calendars and sharing A world can hold more calendars than the primary one. A `calendar:` line starts a calendar, and the event lines under it go on it. Put who it is shared with in brackets, each with a role: ``` ## World: calendar Wed 15:00-16:00 Dentist calendar: Team calendar (sam@acme.test reader, ann@acme.test writer) Thu 09:00-10:00 Sprint planning calendar: primary (mira@acme.test free/busy) ``` * Roles: `free/busy`, `reader`, `writer`, `owner`. * `calendar: primary` shares the primary calendar. * A calendar's own details go in `[...]` after it: ``` calendar: Berlin office [timezone: Europe/Berlin; description: Visits and site days] ``` ## World: gmail `## World: gmail` lists the mailbox, one email per line: ``` when from -> to [cc a@b.test] "subject" [LABELS] #thread +file.pdf // body ``` ``` Fri 16:42 Priya Shah -> me "Offsite planning call" #offsite // Could we do an hour on {Thu}, any time between 2 and 4pm? Sat 10:15 Priya Shah -> me "Re: Offsite planning call" #offsite // Thursday is out now. {Fri} 10-12 instead? Mon 08:15 Dana -> me "Invoice 4471" #inv +invoice-4471.pdf // Attached, due Friday. ``` | Part | What it means | Example | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | when | the most recent such weekday before the clock; `Tue-2` two weeks before that; `today 08:30` | `Sat 10:15` | | from / to | `Name
`, or `me` for the mailbox owner | `me -> Mira ` | | cc | optional, after `to` | `cc mira@acme.test` | | labels | optional. Received mail defaults to `INBOX, UNREAD`; mail from `me` to `SENT`. System labels by id (`INBOX`, `STARRED`, `IMPORTANT`, `DRAFT`); any other name becomes a label of the user's own | `[INBOX, STARRED]`, `[INBOX, Project X]` | | `#thread` | lines with the same key share a thread | `#offsite` | | `+file` | an attached file, by name (no spaces). The content is a stand-in | `+invoice-4471.pdf` | | body | the text after `//` | `// Free {Thu} 2-4pm` | **Drafts.** A line from `me` labelled `[DRAFT]` is a draft already waiting. Your agent can list it, edit it and send it: ``` Fri 17:10 me -> Priya Shah "Re: Offsite planning call" [DRAFT] #offsite // Thursday works, 3pm? ``` **Dates in a body.** Write days in a body as `{Thu}` or `{Thu+1}`. They become dates, such as "Thursday 15 October", when the world is made. "Next week's Thursday" in an email sent on a Saturday reads two ways; a date does not. ### Mail that arrives mid-task A line that starts `after message.send#1:` is hidden when the world starts. It lands in its thread, unread, when your agent sends its first email: ``` after message.send#1: Sat 10:15 Priya Shah -> me "Re: Call" #call // Sorry, Thursday is out after all. ``` Use it for a change of plan your agent should notice before it reports back. To make mail arrive at a moment you choose instead, use `twin world trigger` (see [Run your agent](/twins/using-twins/run-your-agent.md#make-things-happen-mid-run)). ### Mailbox settings Mailbox settings go among the emails, one per line: ``` filter: from priya@acme.test -> label Project X, archive vacation: on "Away this week" // Back Monday -- for anything urgent, ask Mira. forwarding: assistant@acme.test send as: Support // Best, the support team delegate: ea@acme.test imap: off pop: all mail language: fr send as: Secure [smime] cse: mira@acme.test ``` * A filter matches `from`, `to`, `subject` or `query`. It can `label X`, `archive`, `mark read`, `star`, `important`, `delete`, `spam` or `forward a@b`. * `[smime]` on a send-as line gives that address an S/MIME certificate (a stand-in). * `cse:` gives an address a client-side encryption identity. ## People The people in a world are the addresses in it: * **Attendees** in an event's `(...)`, each with an optional reply. * **Senders and recipients** in the mailbox, as `Name
`. `me` is the mailbox owner, the person your agent acts as. * **People a calendar is shared with**, each with a role. Use example domains such as `acme.test` for made-up people. ## Faults A seed file can also make some of your agent's calendar calls fail on purpose, in a `## Faults` section. See [Inject faults](/twins/using-twins/run-your-agent.md#inject-faults). ## Write a seed file from a world `twin world save` writes any world as it stands, as a seed file. Use it to keep the state your agent left, or to start a new seed file from a world you set up by hand. ```bash twin world save world -o after.md twin world create after.md --folder again ```
What a saved seed file cannot hold The seed syntax cannot write everything a world can hold. `twin world save` lists what it left out under `# not saved` in the file, and never drops anything silently. These are: * an event on the clock's own day, or before it; * a rule like "every other Tuesday"; * one occurrence of a series changed on its own; * an all-day event over several days; * mail with no labels at all, or dated after the clock. For an exact copy of everything, use `twin world snapshot` instead. See [See what your agent did](/twins/using-twins/see-what-your-agent-did.md#keep-a-world).
## Common mistakes | What you write | What happens | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `Wed` on the calendar, with the clock on a Wednesday | It means the coming Wednesday after the clock, never the same day | | "Next week's Thursday" in an email body | In an email sent on a Saturday, it reads two ways. Write `{Thu}` or `{Thu+1}`: it becomes a date | ## Next * [Connect your agent](/twins/using-twins/connect-your-agent.md) to the world. * [Run your agent](/twins/using-twins/run-your-agent.md) in it. * [Google Calendar twin](/twins/available-twins/calendar.md): what the calendar twin covers. *** *Last updated: 27 October 2026*