> 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/getting-started/quickstart.md).

# Quickstart

Install the twin CLI, make a calendar world, connect your agent, and read every call it made.

Make a private calendar world, point your agent at it, ask it something, and read back every call it made.

|               |                                                               |
| ------------- | ------------------------------------------------------------- |
| **Time**      | A few minutes                                                 |
| **Twins**     | Google Calendar                                               |
| **You need**  | A terminal on macOS or Linux, and an agent that speaks MCP    |
| **Ends with** | Every call your agent made, on screen                         |
| **Watch out** | Treat the world's token, and the `world/` folder, as a secret |

## Prerequisites

* A terminal on macOS or Linux.
* An agent that speaks MCP: Claude Code, Cursor, Codex or your own.
* A work email with access. Your organization's access comes from Drizz.

## Copy this

Save this as `seed.md` in an empty folder:

```markdown
## Setup
twin: calendar
now: Mon 09:00

## World: calendar
Wed 15:00-16:00  Dentist
Thu 09:00-09:30  Team sync
```

Then run, from that folder:

```bash
brew install DrizzDev/tap/twin-harness   # Mac, or Linux with Homebrew
twin login
twin world create seed.md --folder world
twin world handle world                  # prints the MCP address and the token
claude mcp add --transport http calendar-twin <mcp address> --header "Authorization: Bearer <token>"
# ask your agent: What's on my calendar?
twin world calls world                   # every call your agent made
twin world delete world
```

The steps below explain each line, with npm, uv and other agents.

## Steps

{% stepper %}
{% step %}

### Install the `twin` CLI

{% tabs %}
{% tab title="Homebrew" %}
On a Mac, or Linux with Homebrew:

```bash
brew install DrizzDev/tap/twin-harness
```

Homebrew also sets up tab completion. Upgrade later with `brew upgrade twin-harness`.
{% endtab %}

{% tab title="npm" %}
Needs Node 16+ and Python 3.9+ on your `PATH`.

```bash
npm install -g @drizzdev/twin-harness
```

{% endtab %}

{% tab title="uv" %}
With [uv](https://docs.astral.sh/uv/), install both packages from the release page:

```bash
uv tool install https://github.com/DrizzDev/releases/releases/download/twin-harness-v0.11.1/twin_harness-0.11.1.tar.gz \
  --with https://github.com/DrizzDev/releases/releases/download/twin-harness-v0.11.1/twin_core-0.11.1.tar.gz
```

{% endtab %}
{% endtabs %}

Check it:

```bash
twin --version
```

{% hint style="warning" %}
Avoid a bare `pip install` into your system Python. Most systems refuse it, and every route above keeps the CLI in its own environment.
{% endhint %}
{% endstep %}

{% step %}

### Sign in

```bash
twin login
```

Your browser opens with a short code. Sign in with your work email and approve. A key for this machine is kept in your OS credential store (the macOS Keychain, or the Secret Service on Linux). There is no file to fill in and no token to paste.

Check who you are signed in as:

```bash
twin whoami
```

{% hint style="info" %}
Your organization's access comes from Drizz. If the sign-in says your email has no access yet, ask your Drizz contact.
{% endhint %}
{% endstep %}

{% step %}

### See the twins you can use

```bash
twin --list
```

```console
$ twin --list
calendar  Google Calendar v3: events, recurring events, attendees, other calendars and sharing, free/busy
          world file: ## World: calendar
gmail     Gmail v1: messages, threads, labels, drafts, attachments, filters and mailbox settings
          world file: ## World: gmail

worlds are made on https://twins.drizz.dev with your login
next:   twin world create seed.md --folder world   (a seed file names the twins it uses)
```

{% endstep %}

{% step %}

### Describe and create a world

Make a folder to work in, and save this as `seed.md`. It says what is on the calendar when the world starts.

```markdown
## Setup
twin: calendar
now: Mon 09:00

## World: calendar
Wed 15:00-16:00  Dentist
Thu 09:00-09:30  Team sync
```

`now: Mon 09:00` pins the world's clock, so "Wednesday" always means the same day.

Create the world:

```bash
twin world create seed.md --folder world
```

The world is yours alone. The folder `world/` holds its address and tokens, and every other `twin world` command takes that folder. The world lives 6 hours unless you delete it first.
{% endstep %}

{% step %}

### Connect your agent

`twin world create` printed the world's MCP address. To see the address and the token together:

```bash
twin world handle world
```

Add the world to your agent as an MCP server over HTTP, sending the token as a bearer token:

{% tabs %}
{% tab title="Claude Code" %}

```bash
claude mcp add --transport http calendar-twin <mcp address> --header "Authorization: Bearer <token>"
```

{% endtab %}

{% tab title="Cursor, Codex and others" %}
This detects the MCP clients on your machine and adds the server to them:

```bash
npx add-mcp <mcp address> --name calendar-twin --header "Authorization: Bearer <token>"
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The token gives access to this world. Treat it, and the `world/` folder, as a secret.
{% endhint %}

For your own agent, see [Connect your agent](/twins/using-twins/connect-your-agent.md).
{% endstep %}

{% step %}

### Ask your agent something

Ask your agent:

```
What's on my calendar?
```

It is reading the twin, not your real calendar.
{% endstep %}

{% step %}

### See the calls it made

```bash
twin world calls world               # every call your agent made
twin world calls world --writes      # only the calls that changed something
twin world calls world --follow      # watch them live, from another terminal
```

Save the world as it stands now, as a seed file you can read:

```bash
twin world save world -o after.md
```

More ways to read a world: [See what your agent did](/twins/using-twins/see-what-your-agent-did.md).
{% endstep %}

{% step %}

### Delete the world

```bash
twin world delete world
```

This deletes the world on the server and its folder. Remove the `calendar-twin` server from your agent's MCP settings too, since the world it points at is gone.
{% endstep %}
{% endstepper %}

## In a hurry: `twin start`

`twin start` makes a world in one command and prints the lines that connect your agent to it:

```bash
twin start calendar
```

It prints the world's id, its MCP address and token, an `npx add-mcp` line for Claude Code, Cursor, Codex and others, and a `claude mcp add` line for Claude Code alone. A `twin start` world lives 1 hour by default (`--lease` sets the seconds).

{% hint style="info" %}
A `twin start` world has no folder, so `twin world calls` cannot read it. To read your agent's calls, make the world with `twin world create` as in the steps above.
{% endhint %}

Delete it by its id, or delete every world `twin start` made:

```bash
twin world delete <world id>
twin world cleanup --label start --yes
```

## Common mistakes

| What you write                               | What happens                                         |
| -------------------------------------------- | ---------------------------------------------------- |
| A bare `pip install` into your system Python | Most systems refuse it. Use Homebrew, npm or uv      |
| `twin world calls` on a `twin start` world   | It can't read it: a `twin start` world has no folder |

## Next

* [Key concepts](/twins/getting-started/concepts.md): worlds, seeds, leases, keys and tokens.
* [Describe a world](/twins/using-twins/describe-a-world.md): events, attendees, emails and threads.
* [Run your agent](/twins/using-twins/run-your-agent.md): start your agent with the world's address in its environment.

***

*Last updated: 27 October 2026*