# Set up ShowTake with your coding agent

> Playbook for any AI agent. The user asked you to set up ShowTake from https://showtake.app. Follow these steps in order on the user's Mac. Everything runs locally; the user only acts twice at most: one macOS permission toggle (Mac apps only, macOS requires a human for it) and, if they want Pro, one click on a checkout link you give them.

ShowTake is a Mac app with a built-in MCP server. You drive the user's iOS app (in the Simulator) or Mac app through its tools; ShowTake records every tap and renders demo videos, App Store previews and social cuts. Recordings, screenshots and source code never leave the Mac.

Rules for you, the agent:

- Tell the user in one line what you are about to do before each step that installs or changes something, then do it. Do not ask for confirmation of every command.
- Run every command yourself. Never ask the user to copy, paste or type a command, a key or a path.
- The Free plan needs no account and no key: everything below works before any purchase.
- Stop and report only if a check below fails and the "If it fails" note does not fix it.
- This page is also at https://showtake.app/agents.md (Markdown) and https://showtake.app/agents (HTML). Full docs: https://showtake.app/llms-full.txt.

## 1. Check the Mac

```sh
sw_vers -productVersion   # must be 26.0 or later (macOS 26 Tahoe)
uname -m                  # arm64 (Apple silicon) or x86_64 (Intel): both are supported
```

- macOS older than 26: stop and tell the user ShowTake needs macOS 26 Tahoe or later. Do not install anything.
- Not a Mac (Linux, Windows, a remote container): stop and say ShowTake runs only on macOS.

For iOS apps the Mac also needs Xcode with an iOS Simulator runtime. Check with:

```sh
xcodebuild -version && xcrun simctl list runtimes | grep -i ios
```

If Xcode or a runtime is missing, tell the user (installing Xcode is a large download they must start themselves from the App Store); Mac apps can still be filmed without it.

## 2. Install ShowTake

Already installed? `test -d /Applications/ShowTake.app && echo installed` → skip to step 3.

**With Homebrew** (preferred: updates stay automatic):

```sh
brew install --cask orchestero/tap/showtake
```

**Without Homebrew**: download the notarized disk image, verify it and copy the app:

```sh
set -euo pipefail
tmp="$(mktemp -d)"
curl -fsSL "https://api.showtake.app/download/latest.json?src=agents_md" -o "$tmp/latest.json"
url="$(/usr/bin/plutil -extract url raw "$tmp/latest.json")"
sha="$(/usr/bin/plutil -extract sha256 raw "$tmp/latest.json")"
curl -fL "$url" -o "$tmp/ShowTake.dmg"
echo "$sha  $tmp/ShowTake.dmg" | shasum -a 256 -c -
hdiutil attach -nobrowse -readonly -mountpoint "$tmp/mnt" "$tmp/ShowTake.dmg"
spctl -a -vv "$tmp/mnt/ShowTake.app"   # must say: accepted, source=Notarized Developer ID
ditto "$tmp/mnt/ShowTake.app" /Applications/ShowTake.app
hdiutil detach "$tmp/mnt"
rm -rf "$tmp"
```

`https://showtake.app/download` is the same download for humans; `https://api.showtake.app/download` redirects to the latest disk image.

If `spctl` does not print `accepted` and `source=Notarized Developer ID`, delete the download and stop: never install an unsigned copy.

**For iOS apps also install AXe** (ShowTake uses it to read the simulator screen and send touches):

```sh
brew install cameroncooke/axe/axe
```

## 3. Connect the MCP server

The MCP server is the executable inside the app bundle, started over stdio with no arguments and no environment variables:

```text
/Applications/ShowTake.app/Contents/MacOS/showtake-mcp
```

Register it for the agent you are (user scope, so it works in every project):

| Agent | Do this |
| --- | --- |
| Claude Code | `claude mcp add --scope user showtake -- "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp"` |
| Codex | `codex mcp add showtake -- "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp"` |
| Gemini CLI | `gemini mcp add --scope user showtake "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp"` |
| Cursor | merge the JSON below into `~/.cursor/mcp.json` |
| VS Code | merge the second JSON below into `.vscode/mcp.json` (or the user `mcp.json`) |
| Anything else | a stdio server with the command above |

Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "showtake": {
      "command": "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp",
      "args": []
    }
  }
}
```

VS Code (`mcp.json`):

```json
{
  "servers": {
    "showtake": {
      "type": "stdio",
      "command": "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp"
    }
  }
}
```

Most agents load new MCP servers only in a new session. If the ShowTake tools (`list_targets`, `prepare_ios`, ...) are not available to you after registering, tell the user: "ShowTake is installed. Start a new session in your app's folder and say: film a demo of my app." That is the only restart needed.

## 4. First run and permissions

1. Open the app once so macOS registers it: `open -a ShowTake`. It creates its library in `~/Movies/ShowTake/` and can stay in the background; the MCP server starts it on demand later.
2. Call the MCP tool `doctor` (with `platform` `ios` or `macos`), then `list_targets` from the user's app folder. `doctor` confirms the connection and returns any setup problem (Xcode, simulator runtime, disk, permissions) with its exact fix; `list_targets` lists Xcode projects and schemes, simulators and running Mac apps.
3. **iOS apps** need no macOS permission. Go to step 5.
4. **Mac apps**: call `prepare_macos` with the app (`app_path` or `bundle_id`). It checks Accessibility and Screen Recording for ShowTake. If one is missing it returns `permission_missing` with guidance. Then:
   - open the exact pane for the user:
     - Accessibility: `open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"`
     - Screen Recording: `open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"`
   - tell the user exactly one thing: "Turn on ShowTake in the window that just opened." (For Screen Recording macOS may ask to quit and reopen ShowTake: let it.) Be honest that macOS only lets a person grant this; it is a one-time step.
   - call `prepare_macos` again to re-check. Repeat for the second permission if needed.

Only ShowTake.app needs these permissions, never the terminal or editor.

## 5. Film a first demo

Read the MCP resource `showtake://guide` (or the prompt `film_demo`) before your first take: it is the full filming guide. In short:

1. `prepare_ios` with `project` + `scheme` from `list_targets` (1-5 minutes the first time), or `prepare_macos`.
2. Explore the feature briefly (not recorded), then plan 6-8 steps of 15-30 seconds, one caption of at most 8 words per step.
3. `launch_app` with `fresh: true`, `start_take`, run the planned steps with captions (`tap`, `type_text`, `swipe`, `scroll`, `press`, `wait_for`; each returns the new screen), `end_take`. If `clean` is false, fix what `issues` says and shoot again (up to 3 takes).
4. `save_flow`, then `render` and `export` (the free plan exports `x_16x9` with a watermark).
5. Tell the user where the files are (the `export` result lists each path) and offer to open them with `open <path>`.
6. Launching the app? `export` with `bundle: "launch"` writes a launch kit (Product Hunt gallery and thumbnail, link preview image, X and LinkedIn cards, YouTube/X/vertical videos and a README of what goes where); `screenshot` with `bundle: "app_store"` writes the App Store screenshot set at the required sizes (Pro).

A good first request to film, if the user gave none: the app's main feature end to end, e.g. "create an item and mark it done".

## 6. Upgrade to Pro (only when the user asks, or an export answers `license_required`)

Pro unlocks every preset (App Store previews, vertical and square cuts), 4K, no watermark and batch replays. Prices: https://showtake.app/pricing.md

| Plan id | Plan | Price (USD) | Macs |
| --- | --- | --- | --- |
| `pro_monthly` | Pro Monthly | $9 /month | 2 Macs |
| `pro_yearly` | Pro Yearly | $49 /year | 2 Macs |
| `lifetime` | Lifetime | $129 one-time | 2 Macs |
| `team_yearly` | Team | $39 /seat/year | 2 Macs per seat, 3-50 seats |

1. Ask the user which plan they want if they did not say (default: `pro_yearly`).
2. Call the MCP tool `upgrade` with `{"plan": "<plan id>"}` (Team: add `"seats"`, 3-50). It returns a `checkout_url` bound to this Mac and the price, or `already_pro` when there is nothing to buy.
3. Give the user the price and the `checkout_url` as a link: "Open this link to pay. ShowTake activates itself on this Mac when the payment goes through." This is the only thing the user does. Never fill in payment details yourself. All sales are final, so make sure the user picked the plan they want.
4. ShowTake waits for the payment and activates itself: no license key to copy or paste. `license_status` shows `pending_checkout` until then. After the user says they paid, call `license_status` every 30 seconds for up to 10 minutes and confirm the plan to the user.
5. If the link expired (`expires_at` passed, about 2 hours), call `upgrade` again for a fresh one.

If `upgrade` answers `seats_full`, the license already runs on every allowed Mac: list the Macs from the answer and tell the user to free one at https://showtake.app/manage. If the user already has a key from an email, they can paste it in ShowTake → Settings → License instead.

## Troubleshooting

Every ShowTake error is JSON with `code`, `message`, `fix` (ordered steps: `shell` commands you run, `tool` calls, `edit_project`, `open_url`, `ask_user`), `retryable`, `needs_user` and `tell_user`. Follow `fix` in order, then retry when `retryable` is true. When `needs_user` is true, say the `tell_user` sentence to the user as it is and wait; steps with `needs_password` are `sudo` commands for the user to run in Terminal, never for you.

1. On a new Mac, or when an error is unclear, call the MCP tool `doctor` (`{"platform": "ios"}` or `"macos"`). It checks macOS, Xcode (selected, license, first launch), iOS runtimes and device types, disk space, the built-in AXe, permissions, the app and MCP versions, the license and the network, and returns each problem with its fix. `prepare_ios` / `prepare_macos` run the same checks and fail fast with the same errors.
2. Before the MCP server is connected (no ShowTake tools yet): `brew` not found → use the "Without Homebrew" install; tools do not appear → check the registration (`claude mcp list`, `codex mcp list`, ...) points at `/Applications/ShowTake.app/Contents/MacOS/showtake-mcp`, then ask the user to start a new agent session.
3. Every code, its meaning and fix: https://showtake.app/docs/troubleshooting.md.
4. Still stuck, or the user wants to report a bug or suggest something: call the MCP tool `send_feedback` with `kind`, a `message` (tool calls, take ids, error `code` and `message`, expected vs actual) and the evidence the user agreed to (`attachments: [{"path": …}]` or `[{"take_id": …}]`, `screenshot: true`). ShowTake opens the report in its Send Feedback window and the user presses Send; nothing is sent before that. Relay `tell_user` when it answers `awaiting_user`, and the `reference` when it answers `sent`. Details: https://showtake.app/docs/feedback.md. Without the MCP server: email team@showtake.app.

## Uninstall

`claude mcp remove showtake` (or the agent's equivalent), then `brew uninstall --cask showtake` or move `/Applications/ShowTake.app` to the Trash. Takes stay in `~/Movies/ShowTake/` until the user deletes them.

## What never leaves the Mac

- Recordings, takes, flows, screenshots and exports stay in `~/Movies/ShowTake/`.
- The user's source code, app screens and your prompts are never sent anywhere by ShowTake.
- ShowTake goes online only to check the license (a hash of the Mac's hardware id, no name or files), look for updates and, unless the user turns it off in Settings, send anonymous usage counts and crash reports.
- Payment happens on the checkout page in the user's browser; ShowTake never sees card details.