# Set up Morty

Connect this Agent to Morty so the user can continue the work in their browser.
Stop the original task; complete only this setup in the current session.

Chat origin: https://morty.build

## Run

1. Identify the actual operating system, current shell, and original working directory.
   Keep Node, the Agent, and working directory in the same operating system. WSL is Linux;
   do not mix its executables or paths with native Windows ones.
2. Ensure Node.js 22.19+ (22.x), 24.20+ (24.x), or 26.x and npm (including npx) are installed.
   Setup uses the invoked Morty CLI release for pairing and daemon startup. Old users must reinstall and pair again; old Morty state is never inherited.
   Do not install Morty globally.
   Choose your own harness: Codex = `codex`, Claude Code = `claude`, Pi = `pi`.
   Honor an explicit user choice; never substitute another harness.
   Setup reads the current session from the harness itself; do not look up or ask
   for a session ID.
3. Use the installed `morty` CLI. If it is not installed, run it with
   `npx --yes @portalcrew/morty@latest` instead of `morty` in the commands below.
   Do not download or run a separate setup script. Stop if installation fails.
4. Run the following command with real values and shell-appropriate quoting.
   Use the original absolute working directory.

```text
morty setup --base-url https://morty.build --cwd <absolute-current-working-directory> --harness <own-harness-id>
```

The browser that opens the link keeps access for seven days. Only when the user asks for a different period, add
`--device-access 1h`, `--device-access 1d`, or `--device-access 30d`; nothing longer than 30 days is available.

The CLI keeps this computer's Morty identity in the operating system's local
application data directory for the current user, which is not synced to other
computers, and protects it using filesystem permissions. Each computer has its own.
Do not copy it to a repository, a synced folder, or another computer.
The CLI reuses the saved identity and Computer for this origin and reconnects an
active managed connection when possible. If the saved Computer is no
longer managed here, setup stops with `COMPUTER_REPLACEMENT_REQUIRED` before replacing
anything. Explain in the user's language: **I cannot find this computer's original
connection configuration. Setting up a new connection will invalidate earlier
sharing links and browser access, and you will need to share a new link. Continue?**
Wait for explicit approval unless the user already authorized both the reset and
revoking earlier shared access. Merely asking to run setup or reconnect is not approval.
After approval, rerun the same command with `--replace-computer <computerId>`, using
the exact `computerId` from `error.replacement`. Approval applies only to that computer.
Do not retry with this option automatically, delete local state, or create another
identity to bypass confirmation. If the user declines, stop and keep the saved state.
Approved replacement keeps the user, replaces the Computer, and pairs a
new Computer. Links and browsers from the replaced Computer stop working.
Morty owns Computer connection state and identifiers; do not save or back them up yourself.
Normal setup and reconnection need no registration, separate bind command, or confirmation.

## Finish

Keep progress in this session and wait for `status: "ready"` or an error (at most
five minutes). The daemon keeps the Computer online after the command exits.
Only ready confirms setup; a working chat reply is a separate check.

Return the exact clickable `url` and the working directory from the `workspace` field.
In a terminal, setup prints the QR code at the end of its own command output after ready when the code fits the
terminal, and your interface folds that output. Never use image syntax there, and never redraw, transcribe, or
regenerate a QR code in your reply. Instead tell the user that the QR code is in the setup command's output and how to
expand it: Codex `Ctrl+T`, Claude Code `Ctrl+O`; otherwise, your interface's expand control. When the output says no
QR code fits, give the link and the PNG path instead.
In a GUI that displays inline images, display the owner-only PNG at `qrPath` when present; otherwise return the URL.
If `qrPath` is null, explain that the QR image is unavailable and use the link. Never open,
preview, or redeem the handoff URL yourself. Tell the user: **Open this link or
scan the QR code to chat within 10 minutes. It works on one device only and opens the same
user and Computer; that device keeps access until <`accessExpiresAt` in the user's local time>. Keep the Computer online.
You can bind an account later.**
Also tell the user, in their language: **If you want to revoke these sharing links
later, come back and tell me: "Revoke all links I previously shared from this computer."
I can do that for you.** Include this reminder whenever you deliver a new sharing
link; knowing the command yourself does not replace telling the user.
When `computer` is `"replaced"`, also tell the user, in their language: **This computer's
original connection configuration was missing, so setup started a new connection with your approval, and links and
browsers from this computer's earlier Morty setup stopped working. Use the new link.**

On `status: "replacement_access_revoked"`, immediately tell the user that earlier
sharing links and browser access have been revoked and the new connection is still
being set up. Do not wait for ready to report this access change.
On failure, also report `error.replacementAccess.message` when present. A `kind` of
`"unknown"` means the request may have revoked earlier access even though its reply
was not received; never say the old links are still valid. A `kind` of `"revoked"`
with `setupReady: false` means earlier access was revoked but the new setup is unfinished.
Keep the saved identity and continue recovery using the same approved Computer when
approval is still required. Do not request a second approval for the same previously
authorized replacement, and never carry approval over to a different Computer.

On failure, use `error.code` and the private Computer log, and follow the `nextStep`
in `error.computer`, `error.harness`, `error.binding` or `error.savedIdentity` when present.
`SAVED_IDENTITY_ORIGIN_MISMATCH` means this computer's saved identity belongs to another
Morty origin; setup changed nothing. Never delete or edit the saved state to get past it. Fix installation or
authentication for the selected harness; do not silently choose another.
Keep saved credentials private. Do not output tokens, pairing tickets, or private
configuration; only the ready handoff URL is intended for the user.

Managing previously shared access:
- When the user asks to revoke all previously shared access from this computer, run `morty revoke-all-access`, as the same user on the same computer as setup. The command defaults to the origin in the saved local configuration; `--base-url <same Morty origin>` is optional and must match that saved origin. No harness, session ID, or workspace argument is needed. Use the same CLI installation as setup; never put local credentials in command arguments or output.
- This command uses the original locally saved identity, revokes previous sharing links and all other Morty credentials for its current Computer (including recovery credentials), and replaces this computer's own local credential, so a copy of it stops working too; setup saves the replacement itself, so new sharing links can still be created. It does not stop the daemon or its tasks. It also closes chat windows already open with the revoked access. If it fails with `SESSION_ACCESS_REVOCATION_UNAVAILABLE`, the access is already revoked but windows already open elsewhere are not closed yet; run the same command again, which is safe and finishes closing them.
- Report success only after `status: "access_revoked"`. A missing local identity is an error; do not run setup or create a new identity to conceal it. This command is scoped to the Computer saved in this local configuration, not other installations; a Computer that setup replaced already ended everything shared from it.

Returning Agent sessions to the computer:
- When the user explicitly asks to release Morty Agent sessions so they can continue in the native Agent CLI or GUI, their request authorizes running `morty release` as the same operating-system user as setup. Do not ask for a second confirmation. It releases every idle Morty Agent session on this computer while Morty stays connected and pairing and Agent-native history are retained. A session that is still working, including this one, is not released.
- If the running daemon must be updated, run `npx --yes @portalcrew/morty@latest restart`, then retry release. Restart stops the running daemon and starts it from the invoked Morty release. `start` only ensures a daemon is running and reuses an existing daemon without upgrading it.
- After it succeeds, give recovery instructions in their language. Run the Agent CLI from the original working directory. Codex: `codex resume` opens its session picker; its GUI can be restarted and the conversation selected. Claude Code: `claude --resume` opens its picker, while `claude --continue` chooses the most recent conversation in that directory; restart its GUI and select the conversation if needed. Pi: `pi --resume` opens its picker, while `pi --continue` chooses the most recent session in that directory. A picker is safer than guessing a session ID. Tell the user to exit the native session before continuing it in Morty again; continuing in Morty reopens it. To continue this conversation natively, they can run `morty release` in their terminal after this reply finishes.
