# 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 `. 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": ""}` (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. --- # ShowTake: app demo videos filmed by your coding agent > Mac app with a built-in MCP server. Your agent drives your iOS app in the Simulator or your Mac app; ShowTake records every tap and renders zooms, captions, App Store previews and social cuts. Source: https://showtake.app/ Coding agents: to install and set up ShowTake for your user, follow the playbook at https://showtake.app/agents.md. ## You built it in an hour. Filming it takes a day. Your coding agent wrote the app in an afternoon. The demo video is still a manual job: a screen recorder, a video editor and Apple's spec page open side by side, and every change means doing it again. - **Take after take**: One mistyped letter, a keyboard left open or a notification banner over the screen, and the whole recording starts over. - **Zooms by hand**: You scrub the timeline to find each tap, then nudge zoom boxes until they stop drifting off the button. - **Rejected by App Store Connect**: Wrong resolution, 60 fps, 34 seconds, a device frame around the screen: you find out after the upload. - **Then it starts again**: A redesigned screen, a German version or a 9:16 cut for social video means filming everything from scratch. ## Everything a demo needs, in one take Your agent drives the app; ShowTake records every action with its exact position and time, then turns the take into finished videos. ### Your agent films the takes Ask for a demo in one sentence. Your agent builds the app, opens a clean simulator with the status bar at 9:41, learns the path to the feature and plans six to eight captioned steps. ShowTake judges every take, and the agent reshoots the weak ones without asking you. - Works with any coding agent that can use MCP tools; setup is one command - Each take is checked: too short, keyboard left open, a step that changed nothing, a failed tap - Up to three takes on its own, then it tells you what blocked it ### Zooms that land on the right button Every tap, keystroke and swipe is logged with the frame of the element it hit, so the camera does not guess from pixels. It plans shots from that log: it arrives just before the tap, frames the whole button or text field, holds while the result shows and eases back out. - No keyframes to set; nearby actions share one shot instead of bouncing in and out - Zoom strength subtle, default or punchy, or off - Change any zoom in the review screen before you export ### Pacing without the waiting A raw take is slow: builds, screen reads, typing and loading spinners. ShowTake cuts the idle time between steps and keeps every action and its result at real speed, so a minute of recording becomes a tight demo of about 20 seconds. - Typing and loading play faster, with smooth ramps back to real speed - Taps and their results always play at 1×, so nothing looks rushed - Trim the start and end in the review screen if you want it shorter ### App Previews that pass Apple's checks The App Preview presets export the real screen, full-bleed, at Apple's sizes, 30 fps and 15 to 30 seconds, with the stereo audio track Apple expects. A validator measures each file after export and blocks it when a rule fails, so the upload does not bounce. - iPhone 6.9" (886×1920), iPhone 5.5", iPad and Mac (1920×1080) - Screenshots at every App Store size, from the required iPhone 6.3" (1206×2622) to Mac 2880×1800 - Captions with a price or the word "free" are flagged before export ### One take, every format Render once and export App Store, YouTube, X, TikTok and LinkedIn versions from the same take, plus screenshots and launch images from its key moments. Social cuts get a phone or window frame, a background and captions; App Previews stay plain, as Apple requires. Every file comes back with its measured size, frame rate, codec and length. - 16:9, 1:1 and 9:16, up to 4K - Eight backgrounds, device or window frames, caption styles - H.264 by default; ProRes 422 HQ or HEVC when you ask for it ### Replays in any language A clean take saves as a flow, a plain YAML file of the steps. Replay it after a redesign, or in German and Japanese in one call, with no agent and no tokens. Your agent translates the captions once, and each language's video shows its own. - Re-film every language and device in one batch (Pro) - Needs a localized app; steps that target accessibility ids work in every language - The same flow keeps your demo current after each release ### Mac apps, too ShowTake launches your Mac app, sizes its window to 16:9 and records only that window: no desktop, menu bar or other apps. The pointer travels to each control the way a person would, so hover effects show, and every click is logged for the zoom. - Mac App Preview at 1920×1080 and social cuts in window chrome - macOS asks once for Accessibility and Screen Recording - Keep hands off the mouse while a Mac take records ### Bring your own recording Already have a screen recording from QuickTime or the Simulator? Import it. ShowTake finds where the screen changed, scrolled or moved to a new screen, cuts the idle time and zooms on the activity; your agent adds the captions. - .mov or .mp4, from an iOS app or a Mac app - Exports to the same presets as a filmed take, App Previews included - Detects the iOS keyboard, so captions move out of its way ## Launch everywhere from one take Product Hunt, the App Store, X, Shorts, a link preview: ask your agent for a launch kit and ShowTake writes every file in the size, format and quality each platform needs, checked before you upload. Details and every size: https://showtake.app/docs/launch-assets ## How it works 1. **Paste one prompt**: Copy the prompt into your coding agent. It installs ShowTake, connects its MCP server and checks what your Mac needs. Rather do it by hand? Download the app and add one command to your agent. 2. **Your agent films**: It builds your app, plans the steps with captions, records and retakes until a take is clean. Building takes one to five minutes; you keep working meanwhile. 3. **Export videos and images**: Ask for the videos and images you need: App Store previews and screenshots, launch-site galleries, social cuts. The files land in the take's exports folder, each checked for size, format and length, ready for App Store Connect, Product Hunt or your feed. ## Built for App Store rules App Store Connect turns a preview away for one wrong number: the size, the frame rate, a second too long. ShowTake exports to Apple's rules and checks each file against them before you upload. - **Exact sizes**: Every current App Preview size for iPhone 6.9" to 5.5", iPad 13" and 11", and Mac, in portrait or landscape. - **15 to 30 seconds, 30 fps**: The cut fits the length window, at a constant frame rate, H.264 High at Level 4.0, with a stereo audio track. - **The real screen, nothing else**: No device frame, background or zoomed-out screen: App Previews show your app full-bleed, as Apple requires. - **Checked after export**: A validator reads each file back and lists any rule it breaks, with the fix, before the file goes anywhere. ## Install - Download: https://showtake.app/download (notarized, macOS 26 Tahoe or later, Apple silicon and Intel) - Homebrew: `brew install --cask orchestero/tap/showtake` - Connect Claude Code: `claude mcp add --scope user showtake -- "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp"` - Other agents: https://showtake.app/docs/mcp-setup.md ## Your recordings stay on your Mac ShowTake records, renders and exports on your Mac. Nothing you film is uploaded anywhere. - **Local by design**: Recordings, screenshots, flows and your source code never leave your Mac. Takes live in a folder you choose. - **Online for three things**: Checking your license, looking for updates and, unless you turn it off, anonymous usage counts and crash reports. - **Signed and notarized**: A notarized download with automatic updates and a Homebrew cask, sold here and not on the Mac App Store. ## Pricing Free with a watermark (1080p X 16:9 export). Pro, Lifetime and Team unlock every preset: https://showtake.app/pricing.md ## Questions ### Which AI agents work with ShowTake? All of them: any AI agent or app that can use MCP tools. ShowTake ships its MCP server inside the app, so setup is one command. ### Do I have to set anything up myself? Usually not. Paste the prompt from this page into your coding agent: it installs the app, connects the MCP server and films a first demo. macOS asks you once to allow Accessibility and Screen Recording for Mac takes, and buying Pro is one click on the checkout link your agent gives you. ### Can I edit the video myself? Yes. The review screen in the app shows the rendered take with its zooms, captions and trim, and you can change any of them before exporting. Your agent can make the same changes through the render tool. ### Does anything leave my Mac? No recording, screenshot or line of source code leaves your Mac. ShowTake only goes online to check your license, look for updates and, unless you turn it off, send anonymous usage counts and crash reports. ### What do I need to film an iOS app? macOS 26 Tahoe or later, Xcode with an iOS Simulator runtime. Everything else ShowTake needs to read the screen and send touches is built in. Your agent works in the repo of the app as usual. ### Can it make App Store screenshots and Product Hunt images? Yes, from the same take as the video (Pro). ShowTake writes App Store screenshots at every size App Store Connect accepts, including the required iPhone 6.3" set (1206×2622), iPad 13" and Mac 2880×1800, as plain captures or with a background, headline and device frame. For a launch it writes Product Hunt gallery images (1270×760) and thumbnail, BetaList screenshots, a 1200×630 link preview, X and LinkedIn cards and a README of what to upload where. ### Can it film Mac apps? Yes. ShowTake launches your Mac app, sizes its window and films only that window. It needs the Accessibility and Screen Recording permissions, and tells you how to grant them on first use. ### Will Apple accept the App Preview? The App Preview presets export frameless, full-screen captures at Apple's sizes, at 30 fps or lower, 15 to 30 seconds long, and a validator blocks the export if any rule fails. Review is Apple's call, but the usual technical rejections are checked before you upload. ### Is ShowTake on the Mac App Store? No. The App Store sandbox does not allow the tools ShowTake drives (Xcode, the Simulator, Accessibility), so it is sold here as a notarized download with automatic updates and a Homebrew cask. ### What does it cost, and can I get a refund? The Free plan has every filming tool and exports 1080p X videos with a small watermark. Pro is $9 a month or $49 a year, Lifetime $129 once, Team $39 per seat a year. All sales are final, so film your own app on the Free plan first; subscriptions cancel anytime and stay active until the period ends. ### Windows, Linux or Android? Not today. ShowTake films iOS apps in the Simulator and native Mac apps, on a Mac. --- # ShowTake pricing > Free with a watermark. Pro, Lifetime and Team licenses unlock every export preset, 4K and batch replays. Source: https://showtake.app/pricing | Plan | Price (USD) | Macs | | --- | --- | --- | | Free | $0 | 1 | | Pro Monthly | $9 /month | 2 | | Pro Yearly | $49 /year | 2 | | Lifetime | $129 one-time | 2 | | Team | $39 /seat/year | 2 per seat (3-50 seats) | Prices exclude sales tax or VAT where it applies. A launch discount, when one runs, is shown on https://showtake.app/pricing and applied at checkout. ## Free - Every MCP tool, iOS and Mac takes - Automatic zooms and step captions - 1080p export for X 16:9, with watermark - Saved flows, one replay at a time ## Pro, Lifetime and Team - No watermark, up to 4K - App Preview, header video and screenshots - All social presets: 16:9, 1:1, 9:16 - Batch replays across languages and devices - Custom frames, backgrounds, caption styles - Priority email support ## Buying through your agent Ask your agent to upgrade: it calls the MCP tool `upgrade` and gives you a checkout link. After payment ShowTake activates itself on that Mac; there is no key to paste. Details: https://showtake.app/agents.md ## Questions ### Subscription or lifetime: which should I pick? Pro Monthly and Pro Yearly renew until you cancel and include every update while they run. Lifetime is paid once and includes all future updates. Lifetime is capped at 300 licenses; the counter on this page is the live number. ### How many Macs can I use? Each Pro or Lifetime license runs on 2 Macs at a time. Team licenses get one key with 2 Macs per seat. Move a license by deactivating a Mac in the app's settings or on the license manager page. ### What does the free version include? Everything needed to film: all MCP tools, iOS and Mac takes, automatic zooms, captions and saved flows. Exports are 1080p, X 16:9 only, with a small watermark, and a flow replays one run at a time. No account or network needed. ### Can I get a refund? No, all sales are final. The Free plan has every filming feature, so try ShowTake with your own app first. Subscriptions can be cancelled any time and stay active until the period ends. Wrong or duplicate charges are corrected: email support. ### Can I cancel a subscription? Anytime, from the license manager page. Pro stays active until the end of the period you paid for; nothing renews after that. ### Does anything leave my Mac? No recording or source code ever leaves your Mac. ShowTake goes online only to check your license, look for updates and, unless you opt out, send anonymous usage counts and crash reports. ### Are taxes included? Prices are in US dollars. Sales tax or VAT is added at checkout where the law requires it, and you get a proper invoice. --- # Install ShowTake > Download or brew-install ShowTake and check the first launch. Everything iOS needs is built in. Source: https://showtake.app/docs/install ShowTake is a Mac app with its MCP server inside the bundle. Install it once per Mac. ## Requirements - **macOS 26 Tahoe or later.** - **For iOS apps:** Xcode with an iOS Simulator runtime (ShowTake builds your scheme with `xcodebuild` and runs it in its own simulator). Nothing else: ShowTake ships with the open-source [AXe](https://github.com/cameroncooke/AXe) tool built in, which it uses to read the simulator's accessibility tree, type and send touches. - **For Mac apps:** the Accessibility and Screen Recording permissions for ShowTake ([macOS permissions](https://showtake.app/docs/permissions)). ## Install the app Download the disk image from [the download page](https://showtake.app/download), open it and drag **ShowTake** to **Applications**. The app is signed with a Developer ID and notarized by Apple, so it opens without warnings, and it updates itself in the background. Or with Homebrew: ```sh brew install --cask orchestero/tap/showtake ``` You do not need to install AXe separately: ShowTake uses its own copy inside the app, and a Homebrew `axe` on your Mac is never used unless you point ShowTake at it on purpose (`defaults write app.showtake.ShowTake AXePath /opt/homebrew/bin/axe`; `defaults delete app.showtake.ShowTake AXePath` goes back to the built-in copy). ## First launch Open ShowTake once. It creates its library in `~/Movies/ShowTake/`, where every project keeps its takes, flows and exports: ```text ~/Movies/ShowTake// project.json takes//raw.mov, events.json, flow.yaml flows/.yaml exports/ ``` You do not need to keep the app open: the MCP server starts it in the background when your agent calls a tool. ## Next [Connect your agent](https://showtake.app/docs/mcp-setup), then ask for a demo. --- # Connect your coding agent > Add the ShowTake MCP server to any AI agent. Examples for popular agents below. Source: https://showtake.app/docs/mcp-setup The MCP server is the executable `showtake-mcp` inside the app bundle. It speaks MCP over stdio, so every agent that can start a local MCP server can use it. The path is always: ```text /Applications/ShowTake.app/Contents/MacOS/showtake-mcp ``` ## Claude Code ```sh claude mcp add --scope user showtake -- "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp" ``` `--scope user` makes ShowTake available in every project. Check it with `claude mcp list`. ## Codex ```sh codex mcp add showtake -- "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp" ``` Or add it to `~/.codex/config.toml` yourself: ```toml [mcp_servers.showtake] command = "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp" ``` ## Cursor Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "showtake": { "command": "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp", "args": [] } } } ``` ## Gemini CLI ```sh gemini mcp add --scope user showtake "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp" ``` ## VS Code Add this to `.vscode/mcp.json` in your project, or run **MCP: Add Server** from the command palette and choose a stdio server: ```json { "servers": { "showtake": { "type": "stdio", "command": "/Applications/ShowTake.app/Contents/MacOS/showtake-mcp" } } } ``` ## Other clients Any client that takes a command for a stdio MCP server works: give it the path above, no arguments, no environment variables. ## The working directory matters The server looks for Xcode projects in the **working directory of the agent** (`list_targets`). Start your agent in the folder of the app you want to film, or pass `project` to `prepare_ios`. ## What the agent gets - Tools to prepare, drive and film the app ([tool reference](https://showtake.app/docs/tools)). - The agent guide as the MCP resource `showtake://guide` and the prompt `film_demo`. Most agents read it on their own; if yours does not, tell it "read the ShowTake guide first". --- # Write good demo prompts > What to ask your agent for, so the first take is the one you keep. Source: https://showtake.app/docs/prompts One sentence is enough. The agent plans the steps, writes the captions and retakes on its own. A good prompt names three things. 1. **The app.** "the Todos app", "the Mac app in `build/Notes.app`". If the folder holds several schemes, name the scheme. 2. **The story.** One feature from start to finish: "adding a todo and checking it off", "creating a note and sharing it". 3. **The length or use.** "a 20-second demo", "an App Store preview", "a launch clip for X". ```text Film a 20-second demo of the Todos app showing how to add todos and check them off, and save it as a replayable flow. ``` ## What makes a clean take The agent aims for **6 to 8 steps and 15 to 30 seconds**, one action per step, each with a caption of at most eight words written for the viewer ("Add a new todo", "Mark it done"). After each take `end_take` judges it: too few steps, too short, the keyboard left open, a step that changed nothing or a failed step make it unclean, and the agent shoots again (up to three times). Waiting is not a problem: build time, loading and the agent's thinking are cut out of the render. Judge length by `rendered_estimate_s`, not by the raw recording. ## Tips - **Ask for the captions you want.** "Use the captions: Start in one tap, Write a note, Share it anywhere." - **Give it data.** Seed content makes demos look real. Pass launch arguments for a demo mode, or `photos` and `location` to `prepare_ios` ([demo mode](https://showtake.app/docs/demo-mode)). - **Pick the look.** "in dark mode", "on an iPhone 17 Pro Max", "in German". - **Help it target.** Elements with an `.accessibilityIdentifier` are found by id, which survives copy changes and translations. Without labels the agent falls back to points, which is less robust for replays. - **Keep it one story.** Two features make two videos: ask for two takes and two flows. ## Prompts that work ```text Make an App Store preview of the onboarding: open the app fresh, go through the three onboarding pages and land on the home screen. Light mode, en_US. ``` ```text Film the Mac app at ./build/Release/Notes.app: create a note called "Trip ideas", add three bullet points and pin it. 1280x800 window. ``` ```text Replay the flow add-and-check-todos in en_US, de_DE and ja_JP. ``` --- # Flows and replays > Save a clean take as a flow and re-shoot it for a new build, language or device with no agent. Source: https://showtake.app/docs/flows A **flow** is the list of steps of a take, saved as YAML. Replaying it re-shoots the same demo without an agent and without tokens: for the next build, another language or another device. ## Save a flow After a clean take the agent calls `save_flow` with the take's id and a short name. The file lands in `~/Movies/ShowTake//flows/.yaml`: ```yaml version: 1 name: add-and-check-todos source_take: take-20261111-093410 target: { kind: ios, project: Todos.xcodeproj, scheme: Todos, device: "iPhone 17 Pro" } environment: { status_bar: "9:41", appearance: light, locale: en_US, launch_args: ["-demoMode", "YES"] } steps: - { action: wait_for, id: todos.list, timeout_ms: 8000 } - { action: tap, id: todos.add, caption: "Add a new todo" } - { action: type_text, target: { value: "Untitled Todo" }, text: "Pack the camera", caption: "Name it" } - { action: tap, label: "Pack the camera", role: Cell, caption: "Check it off" } ``` Steps record the most durable selector the element had: accessibility id first, then label and role, then value. You can edit captions or waits by hand. ## Replay Ask the agent ("replay add-and-check-todos") or call the tool yourself: ```json { "name": "add-and-check-todos", "locales": ["en_US", "de_DE", "ja_JP"] } ``` `replay_flow` prepares the target, launches the app fresh, runs every step with deterministic waits and records a new take. Its answer says how each step matched the original take, so a changed screen is caught before you publish the video. - **Several locales or devices** in one call need Pro; the free version replays one at a time. - `retake` re-shoots an existing take with the same target and environment. ## When a replay fails A step fails when its element is gone (`element_not_found`) or a wait runs out (`timeout`). Usually the UI changed: ask the agent to film the flow again and save it under the same name. --- # Export presets and App Store rules > Every output size ShowTake renders, what Pro adds, and the App Preview rules the validator enforces. Source: https://showtake.app/docs/export-presets A take is rendered once (zooms, captions, cuts) and exported to as many presets as you ask for. The agent passes `presets` to `export`; in the app you tick them in the export sheet. | Preset | Size | FPS | Length | Look | Plan | | --- | --- | --- | --- | --- | --- | | App Preview, iPhone 6.9", 6.5", 6.3", 6.1" | 886×1920, 1920×886 | up to 30 | 15-30 s | Full-bleed screen capture: no device frame, no background | Pro | | App Preview, iPhone 5.5" | 1080×1920, 1920×1080 | up to 30 | 15-30 s | Full-bleed screen capture | Pro | | App Preview, iPad 13" and 11" | 1200×1600, 1600×1200 | up to 30 | 15-30 s | Full-bleed screen capture | Pro | | App Preview, Mac | 1920×1080 | up to 30 | 15-30 s | Full-bleed window capture | Pro | | App Store header video (21:9) | 3840×1646 | 30 | 5-30 s | Backgrounds allowed | Pro | | App Store screenshots, iPhone 6.9" | 1320×2868 | still | - | Key frames from the take | Pro | | X, landscape | 1920×1080 | 60 (30 fallback) | up to 140 s | Device frame and background | Free (1080p, watermark) | | X, square | 1080×1080 | 60 (30 fallback) | up to 140 s | Device frame and background | Pro | | TikTok, Reels, Shorts, X vertical | 1080×1920 | 60 | up to 60-180 s by platform | Frame and background, captions inside the safe area | Pro | | YouTube, Product Hunt video link | 1920×1080 | 60 | up to 10 min | Frame and background | Pro | | LinkedIn | 1920×1080, 1080×1080 | 30 | up to 10 min | Frame and background | Pro | The free version exports **X 16:9 at 1080p with a small watermark**. Pro removes the watermark and adds every preset, 4K, custom frames and backgrounds. App Preview exports never carry a watermark: they are Pro only. ## App Preview rules (App Store Connect) Apple rejects previews for technical and content reasons. The App Preview presets are built to pass both, and the **validator stops the export** if any rule fails: - **Exact resolution** for the device class: iPhone 6.9", 6.5", 6.3" and 6.1" share 886×1920 (1920×886 landscape); iPad 13" and 11" use 1200×1600; Mac uses 1920×1080. - **30 fps or lower**, constant frame rate. - **H.264 High profile, level 4.0 or lower**, around 10-12 Mbps (or ProRes 422 HQ). - **15 to 30 seconds** long. - **Stereo AAC audio** at 44.1 or 48 kHz. ShowTake adds a silent track when the take has no sound. - **Only footage of the app**: no device frame, no hands, no background around the screen (Guideline 2.3.4). Touch indicators and captions are allowed. - **No prices** and no "free" claims in captions, since they vary by country. Check any file, made with ShowTake or not, with the free [App Preview checker](https://showtake.app/tools/app-preview-checker). ## App Store header video The 21:9 header video (3840×1646, 5-30 s) introduced in October 2026 may use backgrounds and frames. ShowTake renders it from the same take; check Apple's current spec in App Store Connect help before uploading, as it is new. ## Screenshots Screenshots come from the take's key moments: the settled end of each step, or moments the agent marks. ShowTake writes every size App Store Connect accepts, and the `app_store` set is the one Apple requires plus native large-phone art: iPhone 6.3" (1206×2622) and 6.9" (1320×2868), iPad 13" (2064×2752) or Mac (2880×1800). Plain captures or marketing style (background, headline, device frame). Launch-site images (Product Hunt, BetaList, link previews) have their own page: [Launch assets](https://showtake.app/docs/launch-assets). ## Social presets Social presets keep the device frame and background (six styles, light and dark), render at 60 fps where the platform plays it, and keep captions inside each platform's safe area in vertical cuts. Sizes for every platform are listed on the [video size guide](https://showtake.app/tools/video-sizes). --- # Launch assets and App Store screenshots > The launch kit and App Store screenshot sets ShowTake exports from one take, every size with its source, and what to upload where. Source: https://showtake.app/docs/launch-assets One take gives you more than videos. ShowTake picks the take's key moments (the settled end of each step, or moments the agent marks) and writes screenshots and launch images from them, at the exact pixels each platform asks for. Every file is read back after export: pixel size, PNG or JPEG, no alpha channel, sRGB and the platform's file-size limit. Stills are a Pro feature. ## Ask your agent - "Make the App Store screenshots" → `screenshot` with `bundle: "app_store"`: the required set for the take's platform. Add `style: "marketing"` for a background, a headline per shot (your step captions) and a device frame; `all_sizes: true` for every other accepted size. - "Make a launch kit for Product Hunt" → `export` with `bundle: "launch"`: one folder, `exports/launch-kit/`, with every file below and a `README.md` that says which file goes in which field. - One size only → `screenshot` with `preset`, for example `og_image` or `producthunt_gallery`. ## Image sizes | Group | Slot | Size | Limits | Preset | | --- | --- | --- | --- | --- | | App Store | iPhone 6.3" (Dynamic Island, medium) (required) | 1206×2622 (also 1179×2556) | 1-10 per language, PNG or JPEG, no alpha | `appstore_screenshot_iphone_63` | | App Store | iPhone 6.9" (Dynamic Island, large) | 1320×2868 (also 1290×2796, 1260×2736) | 1-10 per language | `appstore_screenshot_iphone_69` | | App Store | iPhone 6.5" (Face ID, large) | 1284×2778 (also 1242×2688) | 1-10 per language | `appstore_screenshot_iphone_65` | | App Store | iPhone Duo, outer and inner display | 1398×2034 (also inner 2007×2853) | Required from April 2027 for apps built with the iOS 27.1 SDK | `appstore_screenshot_iphone_duo_outer` | | App Store | iPad 13" (required) | 2064×2752 (also 2048×2732) | Required when the app runs on iPad | `appstore_screenshot_ipad_13` | | App Store | Mac (16:10) (required) | 2880×1800 (also 2560×1600, 1440×900, 1280×800) | Required for Mac apps; landscape only | `appstore_screenshot_mac` | | Launch sites | Product Hunt gallery | 1270×760 | At least 1 image, 3 or more suggested | `producthunt_gallery` | | Launch sites | Product Hunt thumbnail (app icon) | 240×240 | JPG, PNG or GIF, up to 2 MB | `producthunt_thumbnail` | | Launch sites | BetaList screenshot | 1600×1200 | Up to 5, about 4:3, 3 MB each | `betalist_screenshot` | | Launch sites | Link preview (Open Graph) | 1200×630 | 1.91:1, under 5 MB for LinkedIn, 8 MB for Facebook | `og_image` | | Social | X image post | 1600×900 | Up to 4 per post, 5 MB each | `x_card` | | Social | LinkedIn image | 1200×627 | 1.91:1, up to 5 MB | `linkedin_card` | | Social | Square post | 1080×1080 | 1:1 | `square_card` | App Store screenshots can be plain captures or marketing images: Apple's Guideline 2.3.3 allows text and image overlays on screenshots as long as they show the app in use. App Previews are different: Guideline 2.3.4 asks for screen captures of the app, so ShowTake never frames them. ## Where each file goes | Platform | Asks for | ShowTake writes | Source | | --- | --- | --- | --- | | Product Hunt | 240×240 thumbnail (2 MB), 1270×760 gallery images, video by link | Thumbnail from your app icon, one gallery image per step, a 1080p video to post on YouTube | [source](https://help.producthunt.com/en/articles/17834537-4-build-your-product-page) | | Hacker News | No media: a link to something people can try | The 1200×630 link preview your page shows when the link is shared | [source](https://news.ycombinator.com/showhn.html) | | App Store | iPhone 6.3" (1206×2622) required, iPad 13" for iPad apps, Mac 16:10; up to 10 each | Every accepted size, raw or with headline and frame, plus the App Preview | [source](https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications) | | BetaList | Square icon, up to 5 screenshots about 4:3 under 3 MB, YouTube link | 1600×1200 screenshots under 3 MB, the same YouTube video | [source](https://betalist.com/help/submitting) | | Peerlist, Uneed, DevHunt | Cover images and a video link; no published sizes | The gallery images and the YouTube video | [source](https://help.peerlist.io/individual/launchpad/guidelines-faqs) | | X | Images up to 5 MB (4 per post), video up to 140 s on free accounts | 1600×900 image cards, 16:9, 1:1 and 9:16 videos under 140 s | [source](https://help.x.com/en/using-x/x-videos) | | LinkedIn | 1200×627 link image (5 MB), video 3 s to 15 min | 1200×627 card, 16:9 and 1:1 videos | [source](https://www.linkedin.com/help/linkedin/answer/46687) | | TikTok, Reels, Shorts | Vertical video; Shorts up to 3 minutes | 1080×1920 with captions clear of the app buttons | [source](https://support.google.com/youtube/answer/15424877) | ## Videos in the launch kit | File | Size | Use | | --- | --- | --- | | `youtube_16x9` | 1920×1080, 60 fps, up to 10 min | Upload to YouTube, paste the link in Product Hunt, BetaList, DevHunt or Peerlist | | `x_16x9` | 1920×1080, up to 140 s | X post video | | `tiktok_9x16` | 1080×1920 | TikTok, Instagram Reels, YouTube Shorts; captions stay clear of the app buttons | | `linkedin_16x9` | 1920×1080, 30 fps | LinkedIn post video | ## Notes - The Product Hunt thumbnail is your app icon. ShowTake reads it from the app it built; if the app has none, the agent passes `icon` with a PNG. - Hacker News takes no images: your Show HN post is a link, and the link preview (`og_image`) is what people see when it is shared elsewhere. - Peerlist, Uneed, DevHunt, Fazier and Microlaunch publish no exact image sizes; the Product Hunt gallery images work there. - Sizes are re-checked against each platform's own pages; full list with sources: [video and image sizes](https://showtake.app/tools/video-sizes). --- # Demo mode for apps with a login > Get past sign-in screens and show realistic data with launch arguments, environment variables and seed data. Source: https://showtake.app/docs/demo-mode ShowTake never asks for real accounts and the agent never guesses credentials. When a login wall, paywall or empty state blocks the feature you want to film, give the app a **demo mode**. ## Launch arguments and environment `prepare_ios` and `prepare_macos` take `launch_args` and `env`; both are saved in the flow, so replays start the same way. ```json { "scheme": "Notes", "launch_args": ["-demoMode", "YES"], "env": { "DEMO_USER": "alex" } } ``` In the app, read them once at launch: ```swift let isDemo = ProcessInfo.processInfo.arguments.contains("-demoMode") || UserDefaults.standard.bool(forKey: "demoMode") if isDemo { session = .signedIn(DemoData.user) // skip the login screen store.load(DemoData.notes) // realistic content } ``` Keep demo mode out of release builds you ship (`#if DEBUG`, or a build setting): ShowTake builds the Release configuration by default, so pass `"configuration": "Debug"` or a dedicated `Demo` configuration if your demo code is behind `DEBUG`. ## Test accounts If the app must sign in for real, use a test account and pass its credentials through `env` from your own shell environment, never in the prompt. When the agent types a password it sets `mask: true`, so the text is hidden in the render and in the logs. ## Seed data and environment (iOS) `prepare_ios` can also: - add images and videos to Photos (`photos`), - set a location (`location: [latitude, longitude]`), - pre-grant permissions so no alert interrupts the take (`privacy: ["photos", "camera", "location"]`), - set the appearance (`light` or `dark`), the locale (`de_DE`) and the status bar time (default 9:41). ## Elements without labels If buttons have no accessibility label or identifier, the agent can only tap by coordinates, which breaks easily on replays. Adding `.accessibilityIdentifier("todos.add")` to the controls in the demo makes takes and flows far more reliable, and helps VoiceOver users too. --- # macOS permissions > Which permissions ShowTake needs, why, and how to grant them. Source: https://showtake.app/docs/permissions Only **ShowTake.app** needs permissions. The MCP helper your agent starts forwards every call to the app over a local socket, so your terminal or editor never needs Accessibility or Screen Recording access. | Permission | Needed for | Why | | --- | --- | --- | | Accessibility | Mac apps | Read the app's controls, press buttons, type and scroll. | | Screen Recording | Mac apps | Record the app's window with ScreenCaptureKit. | | Automation (none) | - | ShowTake does not script other apps through Apple Events. | iOS apps in the Simulator need neither: the simulator is recorded with Xcode's own tools and driven through AXe. ## Granting them `prepare_macos` checks both permissions first. If one is missing, the agent receives the steps to tell you: 1. Open **System Settings → Privacy & Security → Accessibility** (or **Screen & System Audio Recording**). 2. Turn on **ShowTake**. If it is not listed, click **+** and choose it from Applications. 3. For Screen Recording, macOS asks you to quit and reopen ShowTake. ## After an update ShowTake is signed with the same Developer ID on every release, so the permissions stay granted across updates. If macOS still asks again, remove ShowTake from the list with **−** and add it back. --- # License and activation > Enter a key, move it between Macs, renew, and what happens offline. Source: https://showtake.app/docs/license The free version needs no key and no network. A Pro, Lifetime or Team license turns on every export preset, 4K, no watermark and batch replays. ## Activate After checkout you get an email from `team@showtake.app` with your key (`ST-XXXXX-XXXXX-XXXXX-XXXXX`). In ShowTake open **Settings → License**, paste it and click **Activate**. The agent can check the result with the `license_status` tool. ## Macs and seats Pro and Lifetime licenses run on **2 Macs** at a time; Team keys allow 2 Macs per seat. When every slot is taken, activation lists the Macs using them so you can free one: - in ShowTake on the old Mac: **Settings → License → Deactivate this Mac**, or - on the [license manager](https://showtake.app/manage), from any browser: sign in with your checkout email and remove the Mac. ## Online checks and offline use ShowTake refreshes its license about once a day when online. It keeps working offline for **30 days** after the last refresh, so flights and air-gapped build Macs are fine. Only a hash of the Mac's hardware id is sent, never your name, files or recordings. ## Renewals and cancellations Subscriptions renew until you cancel on the [license manager](https://showtake.app/manage); Pro stays active until the end of the paid period, plus a 7-day grace period if a payment fails. Lifetime licenses never expire and include all updates. If a license ends, recordings, flows and settings stay; only Pro exports turn off until you [renew](https://showtake.app/renew). ## Payments All sales are final; try everything on the Free plan first. Wrong or duplicate charges are corrected: email team@showtake.app ([refunds](https://showtake.app/refunds)). --- # Troubleshooting > Every error ShowTake's tools return, what it means and the exact fix, plus the doctor check your agent runs first. Source: https://showtake.app/docs/troubleshooting Your agent usually fixes problems by itself: every ShowTake error tells it what went wrong and what to do, step by step. This page lists the same information, so you can follow along when the agent asks you for something. ## How errors work Every failed tool call returns JSON like this: ```json { "code": "runtime_missing", "message": "No iOS Simulator runtime is installed (a fresh Xcode ships without one).", "fix": [ { "action": "shell", "text": "Download the iOS runtime (several GB, 5-20 min; no password needed).", "command": "xcodebuild -downloadPlatform iOS" }, { "action": "tool", "text": "Check it is installed (ios_runtimes).", "tool": "list_targets" } ], "retryable": true, "needs_user": false, "docs": "https://showtake.app/docs/troubleshooting#runtime-missing" } ``` - `fix` is an ordered list. `shell` steps are commands the agent runs, `tool` steps are ShowTake tool calls, `edit_project` means a change in your code, `open_url` opens a System Settings pane, `ask_user` is a question for you. - `needs_user: true` means only you can do it: a password prompt, a switch in System Settings, installing Xcode, or a payment. The agent then tells you the `tell_user` sentence and waits. Commands marked `needs_password` use `sudo`; the agent gives them to you to run in Terminal instead of running them itself. - `details` carries the evidence: the closest matching elements, compiler errors with file and line, the crash log and its key lines, the installed simulator runtimes. - ShowTake never waits on a hidden prompt. If macOS would ask something, the tool returns an error that says so. ## The doctor check The `doctor` tool checks everything ShowTake depends on in a few seconds: macOS, Xcode (selected, license accepted, first-launch setup done), iOS Simulator runtimes and device types, free disk space, ShowTake's built-in automation helper, Accessibility and Screen Recording, displays, the app and MCP server versions, the license and the connection to showtake.app. Each problem comes back with the same fix as the error below. `prepare_ios` and `prepare_macos` run the same checks first, so a broken setup fails in seconds rather than after a long build. Ask your agent "run the ShowTake doctor" any time something seems off. ## Mac and ShowTake setup ### `macos_too_old` **macOS is too old.** ShowTake needs macOS 26 (Tahoe) or later; doctor reports the running version. 1. Ask the user to update macOS in System Settings > General > Software Update (ShowTake needs macOS 26 or later). 2. Open Software Update for the user. `open "x-apple.systempreferences:com.apple.Software-Update-Settings.extension"` Needs you: the agent asks: “ShowTake needs macOS 26 or later. Please update macOS in System Settings > General > Software Update, then I'll continue.” ### `disk_low` **Low disk space.** Less than 10 GB free on the volume that holds DerivedData or simulator data (builds and simulator clones need several GB). 1. Delete simulators whose runtime is gone (safe). `xcrun simctl delete unavailable` 2. Delete ShowTake's own build cache (rebuilt on the next prepare_ios). `rm -rf ~/Library/Caches/ShowTake/DerivedData` 3. If still short, ask the user before deleting Xcode's DerivedData (~/Library/Developer/Xcode/DerivedData, caches only) or old takes in ~/Movies/ShowTake. 4. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` The agent retries after the fix. ### `disk_full` **Disk full.** A write failed with "No space left on device" (recording, export, build or simulator clone). Cause: The disk ran out of space; the file being written is incomplete. 1. Delete simulators whose runtime is gone (safe). `xcrun simctl delete unavailable` 2. Delete ShowTake's own build cache (rebuilt on the next prepare_ios). `rm -rf ~/Library/Caches/ShowTake/DerivedData` 3. Check how much space is free (need 10 GB or more). `df -h ~` 4. If still short, ask the user what to delete; then retry the call. A take that was recording must be filmed again. The agent retries after the fix. ### `dependency_missing` **A required tool is missing.** A command-line tool ShowTake runs is not installed. 1. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` 2. Follow the fix doctor gives for the failed check. ### `axe_missing` **Built-in AXe is missing.** ShowTake's bundled iOS automation helper (Contents/Helpers/axe) is missing, or the AXePath override points nowhere. 1. If an AXePath override is set, remove it (ShowTake then uses its bundled copy). `defaults delete app.showtake.ShowTake AXePath` 2. Otherwise reinstall ShowTake (the bundle is damaged). `brew reinstall --cask orchestero/tap/showtake` 3. Without Homebrew: download https://showtake.app/download and replace /Applications/ShowTake.app. The agent retries after the fix. ### `axe_quarantined` **AXe is quarantined.** The AXe binary carries the com.apple.quarantine flag (copied from a download), so macOS blocks it or shows a hidden prompt. 1. Remove the quarantine flag from the AXe override (never needed for the bundled copy of a notarized install). `xattr -d com.apple.quarantine "$(defaults read app.showtake.ShowTake AXePath)"` 2. Or drop the override and use the bundled AXe. `defaults delete app.showtake.ShowTake AXePath` The agent retries after the fix. ### `axe_broken` **AXe does not run.** AXe exists but fails to start (killed by code signing, wrong architecture, or a damaged copy). 1. Check the signature of the AXe in use. `codesign --verify --verbose "/Applications/ShowTake.app/Contents/Helpers/axe"` 2. Remove an AXePath override if one is set. `defaults delete app.showtake.ShowTake AXePath` 3. Reinstall ShowTake. `brew reinstall --cask orchestero/tap/showtake` The agent retries after the fix. ### `folder_access_prompt` **macOS is asking about folder access.** ShowTake tried to read a folder macOS protects (Desktop, Documents, Downloads, iCloud Drive, an external or network volume) and macOS is showing the user a permission dialog. ShowTake gives up after 3 s instead of hanging. 1. Ask the user to click Allow in the macOS dialog about ShowTake (it may be behind other windows). 2. Then retry the same call; macOS remembers the answer. 3. To avoid it, keep projects outside Desktop, Documents and Downloads (e.g. ~/Developer). The agent retries after the fix. Needs you: the agent asks: “macOS is asking whether ShowTake may access one of your folders. Please click Allow in that dialog (it may be behind other windows), then tell me.” ### `folder_access_denied` **Folder access denied.** macOS refused ShowTake access to a protected folder (the user clicked Don't Allow once). 1. Open Privacy & Security > Files & Folders for the user. `open "x-apple.systempreferences:com.apple.preference.security?Privacy_FilesAndFolders"` 2. Ask the user to turn the folder on for ShowTake there, then tell you. 3. Or work from a folder outside Desktop, Documents and Downloads (e.g. ~/Developer). The agent retries after the fix. Needs you: the agent asks: “ShowTake is not allowed to read that folder. In System Settings > Privacy & Security > Files & Folders (I've opened it), turn it on for ShowTake, then tell me.” ### `network_unreachable` **No connection to showtake.app.** api.showtake.app did not answer (offline, VPN, firewall or proxy). Filming works offline; license refresh and purchases do not. 1. Check the connection. `curl -sS -m 5 -o /dev/null -w '%{http_code}\n' https://api.showtake.app/healthz` 2. Keep working: Pro stays on offline for 30 days after the last refresh. Purchases need the connection. The agent retries after the fix. ## Xcode ### `xcode_missing` **Xcode is not installed.** iOS takes need the full Xcode app (simulators, xcodebuild). Mac takes of a prebuilt app do not. 1. Ask the user to install Xcode from the Mac App Store (about 10 GB, needs their Apple Account), open it once, then tell you. 2. Open Xcode's App Store page for the user. `open "macappstore://apps.apple.com/app/id497799835"` 3. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` Needs you: the agent asks: “ShowTake needs Xcode to run your iOS app in the Simulator. Please install Xcode from the Mac App Store (I've opened its page), open it once, then tell me.” ### `xcode_select_clt` **Command Line Tools selected instead of Xcode.** xcode-select points at /Library/Developer/CommandLineTools, so xcodebuild and simctl are unavailable although Xcode is installed. 1. Point the developer directory at Xcode (asks for the user's password; the user runs it in Terminal). `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer` (asks for your password) 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` Needs you: the agent asks: “Your Mac uses the Command Line Tools instead of Xcode. Please run this in Terminal and enter your password: sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer” ### `xcode_license` **Xcode license not accepted.** xcodebuild refuses to run until the Xcode license is accepted. 1. Accept the license (asks for the user's password; the user runs it in Terminal). `sudo xcodebuild -license accept` (asks for your password) 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` Needs you: the agent asks: “Xcode's license has not been accepted yet. Please run this in Terminal and enter your password: sudo xcodebuild -license accept” ### `xcode_first_launch` **Xcode first-launch setup not done.** Xcode's first-launch components are missing (a new or updated Xcode that was never opened). 1. Install the components (asks for the user's password; or the user opens Xcode once and clicks Install). `sudo xcodebuild -runFirstLaunch` (asks for your password) 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` Needs you: the agent asks: “Xcode still needs its first-launch setup. Please open Xcode once and click Install, or run this in Terminal: sudo xcodebuild -runFirstLaunch” ### `xcode_broken` **xcodebuild does not run.** xcodebuild exited with an error or hung before doing anything (damaged or half-updated Xcode). 1. See the error. `xcodebuild -version` 2. Check which developer directory is selected. `xcode-select -p` 3. If Xcode is damaged or mid-update, ask the user to finish the update in the App Store or reinstall Xcode. The agent retries after the fix. ## iOS Simulator ### `runtime_missing` **No iOS Simulator runtime.** Xcode has no usable iOS Simulator runtime (fresh Xcode installs ship without one), or not the requested `os` version. 1. Download the iOS runtime (several GB, 5-20 min; no password needed). `xcodebuild -downloadPlatform iOS` 2. Check it is installed (ios_runtimes). tool `list_targets` 3. Then prepare again (omit `os` to use the newest installed runtime). tool `prepare_ios` The agent retries after the fix. ### `runtime_too_old` **iOS runtime older than the app's deployment target.** The app's MinimumOSVersion is newer than every installed iOS Simulator runtime, so it cannot install. 1. Download the newest iOS runtime. `xcodebuild -downloadPlatform iOS` 2. Or lower IPHONEOS_DEPLOYMENT_TARGET of the app target to the installed runtime version (only if the user agrees). 3. Then prepare again. tool `prepare_ios` The agent retries after the fix. ### `device_type_missing` **Unknown simulator device type.** The `device` passed to prepare_ios is not a device type this Xcode knows (details.closest lists the nearest names). 1. Use one of the names in details.closest or list_targets inventory.ios_device_types. tool `list_targets` 2. Prepare again with that `device` (or omit it for the default). tool `prepare_ios` The agent retries after the fix. ### `simulator_boot_failed` **The simulator did not boot.** simctl boot or bootstatus failed or hung for ShowTake's simulator clone. 1. Shut ShowTake's clone down (details.udid). `xcrun simctl shutdown ` 2. Retry prepare_ios (a new clone is made if needed). tool `prepare_ios` 3. If it fails again, the CoreSimulator service is stale: see coresimulator_stale. The agent retries after the fix. ### `coresimulator_stale` **CoreSimulator service is stale.** simctl hangs or reports a CoreSimulator version mismatch (typical right after an Xcode update). 1. Restart the simulator service (closes every open simulator, also the user's own). `killall -9 com.apple.CoreSimulator.CoreSimulatorService` 2. Check simctl answers again. `xcrun simctl list runtimes` 3. If the error mentions an out-of-date CoreSimulator, ask the user to open Xcode once (it installs the matching components) or restart the Mac. The agent retries after the fix. ### `simulator_accessibility_timeout` **Simulator accessibility did not start.** A new simulator clone did not answer accessibility queries within minutes (the Mac is overloaded or the first boot is slow). 1. Wait a minute; the clone keeps settling in the background. 2. Retry prepare_ios: the settled clone is reused. tool `prepare_ios` The agent retries after the fix. ## Project and scheme ### `project_not_found` **No Xcode project found.** `project` does not exist, or no .xcodeproj/.xcworkspace is under the working directory. 1. List projects under a folder (`path`). tool `list_targets` `{"path":"."}` 2. Prepare with the exact `project` path from that list. tool `prepare_ios` The agent retries after the fix. ### `project_ambiguous` **Several projects found.** More than one project or workspace is under the working directory and `project` was not given (details.found lists them). 1. Pick one from details.found; prefer the .xcworkspace when a project has one (CocoaPods, SPM workspaces). 2. Prepare with that `project` and its `scheme`. tool `prepare_ios` The agent retries after the fix. ### `scheme_required` **Scheme not given.** prepare_ios needs `scheme`; details.schemes lists the project's schemes. 1. Prepare again with the app's scheme from details.schemes (usually named like the app, not a test or framework scheme). tool `prepare_ios` The agent retries after the fix. ### `scheme_not_found` **Scheme not found.** The project has no scheme with that name (typo, or the scheme is not shared). details.schemes lists them, details.closest the nearest. 1. Prepare again with a scheme from details.closest / details.schemes. tool `prepare_ios` 2. If the app's scheme is missing, it is not shared: in Xcode, Product > Scheme > Manage Schemes, tick Shared (creates xcshareddata/xcschemes/.xcscheme). The agent retries after the fix. ### `no_app_target` **Scheme builds no iOS app.** The scheme built, but it produces no .app (a framework, test or macOS scheme). 1. List the schemes and pick the app's. tool `list_targets` 2. For a Mac app use prepare_macos with the built .app instead. The agent retries after the fix. ## Building the app ### `build_failed` **The build failed.** xcodebuild failed for a reason ShowTake could not classify; details.log_tail holds the end of the log. 1. Read details.errors / details.log_tail. 2. Reproduce the build (same flags ShowTake uses) to see the full log. `xcodebuild -scheme -configuration Release -destination 'generic/platform=iOS Simulator' build` 3. Fix the cause, then prepare again. tool `prepare_ios` The agent retries after the fix. ### `compile_error` **The app does not compile.** Swift/Objective-C compiler errors; details.errors lists the first ones with file:line. 1. Fix the errors in details.errors (they are in the user's code), or ask the user whether the branch is meant to build. 2. Prepare again. tool `prepare_ios` The agent retries after the fix. ### `signing_failed` **Code signing failed for the simulator build.** The project forces signing settings (a team, profile or entitlements) that a simulator build cannot satisfy. 1. ShowTake builds with ad-hoc signing (CODE_SIGN_IDENTITY=-, no team). A build phase or xcconfig that hard-codes a profile overrides it. 2. Make the simulator build not require a provisioning profile (e.g. set CODE_SIGNING_REQUIRED/PROVISIONING_PROFILE_SPECIFIER only for sdk=iphoneos*), or ask the user. 3. Or build it yourself for the simulator and pass `app_path`. tool `prepare_ios` The agent retries after the fix. ### `packages_unresolved` **Swift packages could not be resolved.** Swift Package Manager failed to fetch or resolve dependencies (network, private repo, or Package.resolved conflict). 1. Resolve packages and read the error. `xcodebuild -resolvePackageDependencies -scheme ` 2. Private repositories need git credentials for the user's account (ask the user); offline needs a network. 3. Prepare again. tool `prepare_ios` The agent retries after the fix. ### `pods_missing` **CocoaPods not installed for this project.** The project has a Podfile but Pods are missing or out of date, or the .xcodeproj was given instead of the .xcworkspace. 1. Install the pods (in the folder with the Podfile). `pod install` 2. Prepare with the .xcworkspace, not the .xcodeproj. tool `prepare_ios` The agent retries after the fix. ### `carthage_missing` **Carthage frameworks missing.** The project links Carthage frameworks that are not built (Carthage/Build is missing). 1. Build the Carthage dependencies for the simulator. `carthage bootstrap --platform iOS --use-xcframeworks` 2. Prepare again. tool `prepare_ios` The agent retries after the fix. ### `swift_version_mismatch` **Swift or Xcode version mismatch.** The project or a dependency needs a different Swift/Xcode version ("compiled with a newer version", unknown language mode, unsupported swift-tools-version). 1. Check the installed Xcode and Swift. `xcodebuild -version && swift --version` 2. Ask the user which Xcode the project needs; installing another Xcode is the user's call. Needs you: the agent asks: “Your project needs a different Xcode or Swift version than the one installed. Which Xcode version does this project use?” ## The app at launch ### `launch_failed` **The app did not start.** The app was installed but did not come to the front (or simctl launch failed). 1. Relaunch it once. tool `launch_app` `{"fresh":true}` 2. If it keeps failing, check launch_args/env, and look for a crash (app_crashed carries the crash log). The agent retries after the fix. ### `app_crashed` **The app crashed.** The app quit right after launch or during a step; details.crash_log is the report, details.crash_tail its key lines. 1. Read details.exception and details.crash_tail: the crashing frames are usually in the user's code. 2. Fix the crash (or pass the launch_args / env the app needs, e.g. a demo mode that skips missing config). 3. Prepare or relaunch again. tool `launch_app` `{"fresh":true}` The agent retries after the fix. ### `login_wall` **A login or onboarding screen blocks the app.** Reported in `warnings` when the first screen looks like sign-in or onboarding. 1. Look for a demo or UI-test mode in the code (launch arguments such as -UITests, -demo, -skipOnboarding; environment flags) and pass it as prepare_ios `launch_args` / `env`. 2. If there is none, ask the user for demo-mode launch arguments or a test account. Never guess credentials. ### `accessibility_empty` **The screen has no accessible elements.** The app's screen reports no or almost no accessibility elements (custom drawing, game engines, canvases, or a still-loading screen). 1. Observe again after a moment (it may still be loading). tool `observe` 2. Tap by points (`x`, `y` from a screenshot) as a fallback. 3. Suggest adding accessibility identifiers: SwiftUI `.accessibilityIdentifier("add")`, UIKit `view.accessibilityIdentifier = "add"`. The agent retries after the fix. ## Finding elements ### `element_not_found` **No element matches.** The id/label/value matches nothing on the current screen. details.closest lists similar elements, details.screen the current screen. 1. Pick the element from details.closest or details.screen and target it by its id (or label). 2. If details.keyboard is true, the keyboard may cover it: press dismiss_keyboard first. If details.alert is true, an alert is on top: answer it first. The agent retries after the fix. ### `stale_index` **Element number from an older screen.** `index` came from a screen that has changed since (details is the current screen). 1. Target again from details (the current screen), preferably by id or label. The agent retries after the fix. ### `alert_blocking` **An alert or permission dialog is in the way.** A system alert (permission request) or app alert covers the screen; only its buttons are reachable (details.buttons). 1. Tap one of details.buttons to answer it (e.g. "Allow"). 2. For permission prompts, pre-grant them instead: prepare_ios with `privacy` (photos, camera, location, contacts, microphone...). tool `prepare_ios` `{"privacy":["photos"]}` The agent retries after the fix. ### `no_focused_field` **No text field is focused.** type_text without `target` while no keyboard is shown. 1. Pass the field as `target` (ShowTake taps it first). tool `type_text` The agent retries after the fix. ## Takes and sessions ### `not_prepared` **No prepared app.** A driving tool was called before prepare_ios / prepare_macos, or the session was replaced (ShowTake relaunched, or another agent prepared another app). 1. Prepare the app again. tool `prepare_ios` 2. If another agent is using ShowTake on this Mac at the same time, wait for it to finish: one app is driven at a time. The agent retries after the fix. ### `take_running` **A take is already recording.** start_take, prepare or launch_app while a take records. 1. End the running take first (it is saved, not lost). tool `end_take` The agent retries after the fix. ### `no_take` **No take is recording.** end_take or mark without a running take. 1. Start one. tool `start_take` ### `caption_required` **Step needs a caption.** An action during a take had no `caption`. 1. Repeat the call with a viewer-facing `caption` of at most 8 words. The agent retries after the fix. ### `recorder_failed` **Recording failed.** The simulator or window recorder did not start, stopped early or delivered no frames. 1. End the take if one is open, then relaunch and record again. tool `end_take` 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` 3. Mac: the window must be visible on screen (not minimised or on another Space); Screen Recording must be granted. The agent retries after the fix. ### `timeout` **Timed out.** A wait_for or a command ran past its limit. 1. Look at the screen to see what it shows instead. tool `observe` 2. For slow network content, use demo data (launch_args) so takes do not depend on the network. The agent retries after the fix. ### `driver` **The automation layer failed.** A touch, key or accessibility call failed inside the simulator or Mac app. 1. Retry the step once. tool `observe` 2. If it repeats, relaunch the app. tool `launch_app` `{"fresh":true}` 3. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` The agent retries after the fix. ### `command_failed` **A system command failed.** simctl, xcodebuild or another tool returned an error (the message carries its stderr). 1. Read the message. 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` The agent retries after the fix. ## Mac apps ### `permission_missing` **macOS permission missing.** ShowTake lacks Accessibility (to press buttons and read the UI) or Screen Recording (to film the window). details.missing names which. 1. Open the Accessibility pane for the user. `open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"` 2. Open the Screen Recording pane for the user. `open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"` 3. Ask the user to turn ShowTake on there (macOS may ask them to quit and reopen ShowTake), then tell you. 4. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` The agent retries after the fix. Needs you: the agent asks: “macOS needs your OK once: in System Settings > Privacy & Security (I've opened it), turn on ShowTake under Accessibility and Screen & System Audio Recording, then tell me.” ### `mac_app_not_found` **Mac app not found.** `app_path` does not exist or is not an app, or no installed app has that `bundle_id`. 1. See running Mac apps and their paths. tool `list_targets` 2. Find the app. `mdfind "kMDItemContentType == 'com.apple.application-bundle'" -name ` 3. Or build it first and use the .app from the build folder. `xcodebuild -scheme -configuration Release -derivedDataPath build build` The agent retries after the fix. ### `mac_no_window` **The Mac app has no window.** The app runs but shows no window (closed, minimised, still launching, or a menu-bar-only app). 1. Relaunch it. tool `launch_app` 2. If it is minimised or on another Space, ask the user to bring it to the current desktop. Menu-bar-only apps cannot be filmed as a window. The agent retries after the fix. ### `window_offscreen` **The window is off screen.** The app's window is minimised, hidden or outside every display. 1. Relaunch the app: ShowTake places and sizes the window again. tool `launch_app` 2. With several displays, ShowTake uses the main display (the one with the menu bar). The agent retries after the fix. ### `multiple_displays` **Several displays.** Reported by doctor: ShowTake films on the main display. 1. Nothing to do; keep the filmed app on the main display (the one with the menu bar). ## ShowTake app and MCP server ### `app_unreachable` **ShowTake.app is not reachable.** The MCP server could not reach ShowTake.app over its local socket (not installed, not running, crashed, or blocked at first launch). 1. Open ShowTake (from /Applications). `open -a ShowTake` 2. Check it is installed. `ls -d /Applications/ShowTake.app` 3. Not installed: install it. `brew install --cask orchestero/tap/showtake` 4. If macOS showed a dialog on first launch ("downloaded from the internet"), ask the user to click Open. 5. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` The agent retries after the fix. ### `updating` **ShowTake is installing an update.** ShowTake is relaunching into a new version. 1. Wait about 15 s, then retry the call. Prepare again if the call answers not_prepared. The agent retries after the fix. ### `restart_required` **MCP server and app versions do not match.** This MCP server process is an older copy than the running ShowTake.app and cannot talk to it. 1. Ask the user to restart the ShowTake MCP server in their client (Claude Code: /mcp, reconnect showtake). 2. The MCP command must be /Applications/ShowTake.app/Contents/MacOS/showtake-mcp. Needs you: the agent asks: “ShowTake was updated; please restart its MCP server in your agent (in Claude Code: /mcp, then reconnect showtake).” ### `unsupported_version` **File from a newer ShowTake.** A flow or take was written by a newer ShowTake than this one. 1. Check for an update. tool `update_status` 2. Or update with Homebrew. `brew upgrade --cask orchestero/tap/showtake` ### `internal` **Internal error.** Something unexpected failed inside ShowTake. 1. Retry once. 2. Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool `doctor` 3. If it repeats, report it with send_feedback (tool name, arguments, this message; attach the take if there is one). The user reviews and sends it in ShowTake, or uses Help > Send Feedback. tool `send_feedback` `{"kind":"bug"}` The agent retries after the fix. ## License ### `license_required` **Needs ShowTake Pro.** The free plan does not include this (non-watermarked or non-X exports, App Previews, screenshot sets, batch replays). details.state says why (free, expired_*, wrong_mac). 1. Tell the user what needs Pro; do not retry. Free exports: x_16x9 with a watermark. 2. If they want Pro: upgrade returns a checkout link to give them. tool `upgrade` `{"plan":"pro_yearly"}` Needs you: the agent asks: “This export needs ShowTake Pro. Want me to get you a checkout link? Otherwise I can export the free X 16:9 version with a watermark.” ### `license_expired` **Subscription ended.** The Pro subscription ended (valid_until passed). 1. Ask the user to renew at https://showtake.app/manage; ShowTake refreshes by itself afterwards. 2. Check after they renew. tool `license_status` Needs you: the agent asks: “Your ShowTake Pro subscription has ended. You can renew it at https://showtake.app/manage, then I'll continue.” ### `license_offline_too_long` **License not refreshed for 30 days.** ShowTake could not reach the license server for 30 days, so Pro is paused. 1. Check the connection to the license server. `curl -sS -m 5 https://api.showtake.app/healthz` 2. Once online, ShowTake refreshes within a minute; then call license_status. The agent retries after the fix. ### `license_wrong_mac` **License belongs to another Mac.** The stored license was activated on a different Mac (e.g. migrated from a backup). 1. Ask the user to enter their key again in ShowTake > Settings > License (it activates this Mac). Needs you: the agent asks: “Your ShowTake license was activated on another Mac. Please enter your key again in ShowTake > Settings > License.” ### `seats_full` **Every Mac slot of the license is in use.** Activation was refused: the license is active on as many Macs as it allows (details.macs). 1. Ask the user to free a Mac at https://showtake.app/manage, then enter the key in ShowTake > Settings > License. Needs you: the agent asks: “Your license is already active on every Mac it allows. Free one at https://showtake.app/manage, then enter your key in ShowTake > Settings > License.” ### `purchases_closed` **Purchases are not open.** upgrade was called while checkout is closed. 1. Tell the user; keep working on the free plan. ## Render and export ### `export_invalid` **Export failed validation.** A file broke a store rule (App Preview length, size, fps, captions); each file's validation.failures has the rule and its fix. 1. Read files[].validation.failures[].fix. 2. Re-plan with render (trim, captions, cut), then export again. tool `render` The agent retries after the fix. ### `take_not_found` **Take not found.** No take with that take_id in the library. 1. Use the take_id end_take returned (takes live in the ShowTake library, Settings shows where). ## Tool arguments ### `bad_request` **Invalid arguments.** A parameter is missing, has the wrong type or an unknown value (the message names it). 1. Fix the arguments as the message says and call again; the tool's input schema lists every parameter. The agent retries after the fix. ### `not_found` **Not found.** A file, flow or take named in the call does not exist. 1. Check the path or name in the message. ### `unknown_tool` **Unknown tool.** The tool name does not exist in this ShowTake version. 1. Use a tool from tools/list. ### `not_implemented` **Not available in this version.** The tool or option is not implemented in this build. 1. Check for an update. tool `update_status` ## The first iOS take is slow The first `prepare_ios` builds your app in Release and creates ShowTake's clean simulator for that device type: 1 to 5 minutes. Later takes reuse both. ## The keyboard stays open at the end Some apps never dismiss their keyboard. ShowTake tries `dismiss_keyboard`; if the app keeps it, `end_take` reports a note (not an issue) and the take still counts as clean. ## The video has no audio track Takes record no sound. App Preview exports add a silent stereo track because App Store Connect sometimes refuses files without one. ## Still stuck Email support@showtake.app with the tool name, the error `code` and its `message`. Recordings stay on your Mac; we never need them to help. --- # Send feedback and bug reports > Report a bug, ask a question or suggest an idea from ShowTake or through your coding agent, with recordings, screenshots and diagnostics you choose to attach. Source: https://showtake.app/docs/feedback Bug reports, questions, ideas and praise go straight to the ShowTake team. You see everything before it is sent, and nothing leaves your Mac until you press **Send**. ## From the app Open **Help → Send Feedback…** (also in **Settings → Privacy** and the menu bar icon). 1. Pick the kind: **Bug**, **Idea**, **Question** or **Praise**, and write what happened. For a bug: what you did, what you expected, and what happened instead. 2. Add an email address if you want a reply (optional). 3. Attach evidence: drop files on the window or use **Add Files…** (screen recordings, screenshots, logs, JSON, YAML, PDF, ZIP), **Attach a Take** (the take's video, latest render, flow, `render.json` and `events.json`), **Screenshot of ShowTake** or **Crash Reports** (ShowTake's own, with your user name removed). Remove anything with the ✕ next to it. 4. Open **What will be sent** to read the exact report, including the diagnostics, and turn diagnostics off if you prefer. 5. Press **Send**. Large videos upload with a progress bar. You get a reference like `FB-7K2Q-9MXA`; quote it if you write to us about the report. No connection? The report is saved on your Mac and sent automatically when ShowTake can reach showtake.app again, even after a restart. ## Through your coding agent Ask your agent to report it ("send this bug to ShowTake with the last take"). It calls the MCP tool `send_feedback` with a description, the take or files, and the diagnostics. ShowTake then opens the same **Send Feedback** window, marked as prepared by your agent: check it, change anything, and press **Send**, or close it to cancel. Your agent learns whether you sent it and gets the reference. ```json { "kind": "bug", "message": "end_take reports clean=false on step 3 (element_not_found: Save). Replay of flow add-item fails the same way.", "attachments": [{ "take_id": "2026-11-12-0930-add-item", "include": ["raw", "flow", "render"] }], "screenshot": true } ``` The call waits up to 90 seconds for you (`wait_seconds`, at most 300) and answers `sent` with the reference, `cancelled`, `queued` (offline, sent later) or `awaiting_user` with a `draft_id` the agent can check again. Parameters: [MCP tool reference](https://showtake.app/docs/tools#send_feedback). ## What a report contains - Your message, the kind and your reply email if you gave one. - ShowTake's version and update channel, the macOS version, the Mac model and processor type, your license plan and state (never the key), and which coding agent prepared it. - Diagnostics, unless you turn them off: ShowTake's setup check (Xcode, simulator runtimes, disk space, permissions, versions), its recent log of tool calls and errors, and summaries of ShowTake's crash reports. Your home folder and user name, email addresses, license keys and tokens are removed before the report is built. - Only the files you attached. ## Limits | | Limit | | --- | --- | | Attachments per report | 20, 1 GB in total | | Videos (`.mov`, `.mp4`, `.m4v`, `.webm`) | 500 MB each | | Images (`.png`, `.jpg`, `.heic`, `.gif`, `.webp`) | 25 MB each | | Text, logs, JSON, YAML, CSV, crash reports | 10 MB each | | PDF / ZIP | 50 MB / 200 MB | | Reports | 20 per day per Mac | Zip folders before attaching them. For anything larger, send the report without the file and we will reply with a way to share it. ## Privacy Reports are private: they are stored where only the ShowTake team can read them and are deleted after 180 days. Recordings never leave your Mac unless you attach them here and press Send. Details: [privacy policy](https://showtake.app/privacy#feedback-you-send). Prefer to discuss it in public? **Help → Open a Public GitHub Issue…** opens a pre-filled issue you write and publish yourself. --- # MCP tool reference > Every tool the ShowTake MCP server offers, with its parameters, generated from the server's own catalogue. Source: https://showtake.app/docs/tools Tool names are a stable contract: they are never renamed, only added. All tools return JSON; errors are `{ "error": "", "hint": "…" }` ([error codes](https://showtake.app/docs/troubleshooting)). ## `list_targets` List what ShowTake can film: Xcode projects/workspaces and their schemes under `path` (default: the working directory), iOS simulator devices, running Mac apps, and the current session. | Parameter | Type | Description | | --- | --- | --- | | `path` | string | Folder to search for Xcode projects (default: working directory). | ## `prepare_ios` Build the iOS app (Release), clone a clean simulator from ShowTake's golden device (status bar 9:41, en-US), install, launch and return the first screen plus a session_id. Takes 1-5 min. | Parameter | Type | Description | | --- | --- | --- | | `app_path` | string | Prebuilt simulator .app to install instead of building. | | `appearance` | string | light or dark (default light). | | `configuration` | string | Build configuration (default Release: no debug overlays). | | `device` | string | Simulator device type (default "iPhone 17 Pro"). | | `env` | object | Environment variables for the app. | | `launch_args` | array | Extra launch arguments, e.g. demo-mode flags. | | `locale` | string | App locale, e.g. en_US or de_DE (default en_US). | | `location` | array | Simulated location [latitude, longitude]. | | `os` | string | iOS runtime version, e.g. "27.0" (default: newest installed). | | `photos` | array | Image/video files to add to the Photos library. | | `privacy` | array | Permissions to pre-grant: photos, camera, location, contacts... | | `project` | string | Path to the .xcodeproj or .xcworkspace (relative to the working dir). | | `project_name` | string | Library project to file takes under (default: scheme name). | | `scheme` | string | Scheme to build. | | `status_bar` | string | Status bar time (default "9:41"). | ## `prepare_macos` Launch a Mac app, size its window (16:9 by default, for Mac App Previews), check the Accessibility and Screen Recording permissions (returns guidance if missing) and return the first screen plus a session_id and `notes` (desktop clutter, notifications, window size) to relay to the user. | Parameter | Type | Description | | --- | --- | --- | | `app_path` | string | Path to the .app bundle or the app's executable. | | `bundle_id` | string | Bundle identifier of an installed app (instead of app_path). | | `env` | object | Environment variables for the app (executables only). | | `keep_window_size` | boolean | Keep the app's own window size instead of the 16:9 default. | | `launch_args` | array | Extra launch arguments, e.g. demo-mode flags. | | `locale` | string | App locale, e.g. en_US or de_DE (default: the Mac's). | | `project_name` | string | Library project to file takes under (default: app name). | | `window_size` | array | Window size [width, height] in points (default: the largest 16:9 window up to 1600x900 that fits the screen). | ## `launch_app` (Re)launch the prepared app and return its first screen once it is ready for input. fresh=true resets its data first (iOS: reinstall); use it before every take. | Parameter | Type | Description | | --- | --- | --- | | `fresh` | boolean | Reset app data first (default false). | | `session_id` | string | Session from prepare_ios / prepare_macos (default: the current one). | ## `observe` Wait until the UI is still and return the screen: screen_id, title, alert/keyboard flags and a compact element list `[index] Role "label" id=... value=... @x,y,w,h`. | Parameter | Type | Description | | --- | --- | --- | | `depth` | integer | Accessibility tree depth limit (default 40). | | `session_id` | string | Session from prepare_ios / prepare_macos (default: the current one). | ## `screenshot` PNG of the app (simulator screen or window), downscaled. Fallback only: the element list is usually enough. With `take_id`: App Store screenshots and launch images from the take's key frames (the settled end of each step, or `at_ms`), exact store pixels, sRGB, no alpha, each file validated. One `preset`, a `presets` list, or a `bundle`: app_store = the App Store set for the take's platform (iPhone 6.3" 1206x2622, Apple's required class, + 6.9" 1320x2868; iPad 13" 2064x2752; Mac 2880x1800; `all_sizes` adds every other accepted size incl. iPhone Duo), launch = Product Hunt gallery 1270x760 + thumbnail 240x240, BetaList 1600x1200, Open Graph 1200x630, X 1600x900, LinkedIn 1200x627, square 1080x1080. Pro. | Parameter | Type | Description | | --- | --- | --- | | `all_sizes` | boolean | With bundle app_store: every accepted App Store size, not only the required ones. | | `at_ms` | array | Raw take times to capture (default: the end of every step). | | `background` | string | Background of composed images (default: the render style's). | | `bundle` | string | app_store: required App Store screenshot sizes for the take's platform; launch: launch-site and social images. | | `format` | string | png (default) or jpeg; images over a platform's size limit are written as JPEG. | | `headline` | string | Headline on launch/social images (default: the take title). | | `headlines` | array | Marketing headlines, one per shot (default: each step's caption). | | `icon` | string | App icon image for producthunt_thumbnail (default: the prepared app's icon). | | `out_dir` | string | Destination folder (default: the take's exports/screenshots). | | `preset` | string | One still preset. | | `presets` | array | Several still presets. | | `session_id` | string | Session from prepare_ios / prepare_macos (default: the current one). | | `style` | string | App Store screenshots: raw (the real screen, full-bleed; default) or marketing (background + headline + generic device frame; Apple allows this for screenshots, never for App Previews). Launch and social images are always composed. | | `take_id` | string | Take to extract stills from (instead of the live app). | ## `doctor` Check that this Mac can film: macOS, Xcode (selected, license accepted, first-launch done), iOS simulator runtimes and device types, disk space, ShowTake's built-in AXe, Accessibility and Screen Recording, displays, the ShowTake app and MCP versions, the license and the connection to showtake.app. Returns a checklist; every failed check carries an error with ordered `fix` steps (exact commands or tool calls) and, when a human must act, `needs_user` + `tell_user`. Call it first on a new Mac and whenever a tool error is unclear. Takes a few seconds. | Parameter | Type | Description | | --- | --- | --- | | `platform` | string | What you are about to film (default all). | | `project` | string | Optional .xcodeproj/.xcworkspace to check (path, schemes, CocoaPods). | | `scheme` | string | Optional scheme to look for in `project`. | ## `license_status` The license plan, seats and update entitlement of this ShowTake install. No parameters. ## `update_status` ShowTake's version and auto-update state: app and MCP server versions, whether a newer version is downloading or waiting to install, and what blocks it. ShowTake updates itself: it installs when no take, export or tool call is running, relaunches, and this MCP server switches to the new version on its own. check=true checks now; install=true installs a downloaded update now (never during a demo: the prepared session ends). | Parameter | Type | Description | | --- | --- | --- | | `check` | boolean | Check for a new version now (waits up to 30 s for the answer). | | `install` | boolean | Install an already downloaded update now and relaunch ShowTake. | ## `upgrade` Buy Pro for this Mac: returns a checkout_url (bound to this Mac) and the price to give the user. After payment ShowTake activates itself, no key to paste; license_status shows pending_checkout until then. Returns already_pro when there is nothing to buy. | Parameter | Type | Description | | --- | --- | --- | | `plan` **required** | string | Plan to buy. | | `seats` | integer | Team seats (team_yearly only, 3-50, default 3; 2 Macs per seat). | ## `send_feedback` Send a bug report, idea, question or praise to the ShowTake team, with optional evidence: files (video, images, logs, JSON, YAML, PDF, ZIP), takes and a screenshot of ShowTake, plus redacted diagnostics (doctor, recent tool calls and errors, crash summaries). Nothing is sent by this call: ShowTake opens its Send Feedback window with the report and the user presses Send. Waits up to wait_seconds for that; returns status sent (+ reference), cancelled, queued (offline, sent later) or awaiting_user (+ draft_id and tell_user). With draft_id: the status of an earlier report. | Parameter | Type | Description | | --- | --- | --- | | `attachments` | array | Evidence the user agreed to send (20 at most, 1 GB in total; videos up to 500 MB). | | `contact_email` | string | Email for the reply (only if the user gave it). | | `draft_id` | string | Check an earlier report that was awaiting_user (other fields ignored). | | `include_diagnostics` | boolean | Attach the redacted diagnostics (default true). | | `kind` | string | What it is (default bug). | | `message` | string | What was done (tool calls, take ids, error codes), what was expected, what happened. Plain text, up to 20000 characters. | | `screenshot` | boolean | Also attach a screenshot of ShowTake's main window. | | `wait_seconds` | integer | How long to wait for the user's Send (default 90, max 300). | ## `tap` Tap an element (id / label / value / index) or a point (x, y) with a finger-like touch (macOS: accessibility press, click as fallback). Waits for the UI to settle and returns the new screen. | Parameter | Type | Description | | --- | --- | --- | | `caption` | string | Viewer-facing caption for this step (<= 8 words). Required while recording. | | `id` | string | Accessibility identifier (preferred). | | `index` | integer | Element number from the screen `screen_id` (requires screen_id). | | `label` | string | Accessibility label: exact, else case-insensitive contains. | | `nth` | integer | 0-based pick among several matches. | | `role` | string | Role from the screen list (Button, TextField, Cell, CheckBox...) to narrow matches. | | `screen_id` | string | The screen `index` refers to; an older screen is rejected (stale_index). | | `value` | string | Element value, e.g. the placeholder of an unlabeled text field. | | `x` | number | Point x (with y) when no element fits. | | `y` | number | Point y. | | `zoom` | string | Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view). | ## `type_text` Type text at a human pace into the focused field (or tap `target` first), then verify the field shows it (ok=false when keystrokes were lost). Returns the new screen. | Parameter | Type | Description | | --- | --- | --- | | `caption` | string | Viewer-facing caption for this step (<= 8 words). Required while recording. | | `mask` | boolean | Mask the text in renders and logs (passwords). | | `submit` | boolean | Press Return afterwards. | | `target` | object | | | `text` **required** | string | Text to type (US keyboard characters). | | `zoom` | string | Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view). | ## `swipe` One-finger swipe: `direction` (finger movement) across `target` or the screen centre, or explicit from/to points. E.g. swipe left on a row to reveal its actions. Returns the new screen. | Parameter | Type | Description | | --- | --- | --- | | `caption` | string | Viewer-facing caption for this step (<= 8 words). Required while recording. | | `direction` | string | Finger movement. | | `duration_ms` | integer | Gesture duration (default 300). | | `from` | array | Start point [x, y]. | | `target` | object | | | `to` | array | End point [x, y]. | | `zoom` | string | Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view). | ## `scroll` Scroll the content: direction=down reveals content further down. `amount` is the fraction of the screen (default 0.5). Returns the new screen. | Parameter | Type | Description | | --- | --- | --- | | `amount` | number | Fraction of the screen, 0.1-0.8 (default 0.5). | | `caption` | string | Viewer-facing caption for this step (<= 8 words). Required while recording. | | `direction` **required** | string | Content direction. | ## `press` Press a key or button: return, backspace, escape, tab, space, home (iOS), dismiss_keyboard, or a macOS shortcut like cmd+n. Returns the new screen. | Parameter | Type | Description | | --- | --- | --- | | `caption` | string | Viewer-facing caption for this step (<= 8 words). Required while recording. | | `key` **required** | string | Key name or shortcut. | ## `wait_for` Wait until an element is present (gone=true: absent), or with no selector until the UI is still for stable_ms. Fails with `timeout` after timeout_ms. Returns the screen. | Parameter | Type | Description | | --- | --- | --- | | `gone` | boolean | Wait until the element is absent. | | `id` | string | Accessibility identifier (preferred). | | `index` | integer | Element number from the screen `screen_id` (requires screen_id). | | `label` | string | Accessibility label: exact, else case-insensitive contains. | | `nth` | integer | 0-based pick among several matches. | | `role` | string | Role from the screen list (Button, TextField, Cell, CheckBox...) to narrow matches. | | `screen_id` | string | The screen `index` refers to; an older screen is rejected (stale_index). | | `stable_ms` | integer | Stillness required (default 400). | | `timeout_ms` | integer | Hard limit (default 10000, max 60000). | | `value` | string | Element value, e.g. the placeholder of an unlabeled text field. | ## `mark` Add a caption (and optional zoom rectangle) at the current moment of the take, without an action. | Parameter | Type | Description | | --- | --- | --- | | `caption` **required** | string | Caption text (<= 8 words). | | `emphasis` | string | How strongly to zoom. | | `rect` | array | Area to emphasise [x, y, width, height] in points. | ## `start_take` Start recording the app (simulator screen or window) and the step/event log. Launch the app (fresh) first. Returns the take_id. | Parameter | Type | Description | | --- | --- | --- | | `preset_hint` | string | Intended output, e.g. app_preview, x_16x9, tiktok_9x16. | | `session_id` | string | Session from prepare_ios / prepare_macos (default: the current one). | | `title` **required** | string | What the demo shows, e.g. "Add and finish todos". | ## `end_take` Stop recording; writes raw.mov, events.json and flow.yaml, and judges the take: `clean` plus `issues` (too few steps, too short, keyboard left open, no-op or failed steps) and `rendered_estimate_s`. | Parameter | Type | Description | | --- | --- | --- | | `session_id` | string | Session from prepare_ios / prepare_macos (default: the current one). | ## `save_flow` Save a take's steps as a named, replayable flow (flows/.yaml in the project), optionally with caption translations that localized replays (replay_flow with locales) film instead. | Parameter | Type | Description | | --- | --- | --- | | `caption_translations` | object | Captions in other languages for localized replays: locale or language → one caption per captioned step, in the order save_flow returns them in `captions`, e.g. {"de": ["Neues Element", …], "ja": [...]}. | | `name` **required** | string | Flow name, e.g. add-todos. | | `take_id` **required** | string | Take to save. | ## `replay_flow` Re-shoot a saved flow without an agent: prepares the target, launches fresh, runs every step with deterministic waits and records a new take. Returns its take_id and how it matched. With several locales or devices (Pro) it shoots one take per combination and returns them all in `takes`. | Parameter | Type | Description | | --- | --- | --- | | `devices` | array | Device types to shoot (more than one needs Pro). | | `locales` | array | Locales to shoot, e.g. ["en_US", "de_DE", "ja_JP"] (more than one needs Pro). | | `name` | string | Flow name from save_flow. | | `path` | string | A flow .yaml file to replay instead of a saved flow name. | | `project` | string | Library project of the flow (default: search all). | ## `retake` Replay the steps of an existing take as a new take (same target and environment), with no agent. | Parameter | Type | Description | | --- | --- | --- | | `take_id` **required** | string | Take to re-shoot. | ## `render` Plan the finished video of a take and save it as render.json: smart pacing (default) speeds up idle time, waits and typing with smooth ramps while every action and its result play at 1×, the camera zooms on taps and typing, your step captions become on-screen captions, touches get ripples (macOS: a re-drawn pointer), and decorated presets get a device frame or window chrome on a background. Returns the rendered length, zooms, captions and a pre-export check per preset (App Preview rules, license). Fast: nothing is encoded until `export`. | Parameter | Type | Description | | --- | --- | --- | | `captions` | array | Caption edits by step number (as end_take lists). | | `cut` | string | shared (default): one cut fitted to every preset's length rules; per_preset: each preset its own length (e.g. a 30 s App Preview and a 45 s X video). | | `pacing` | string | smart (default): speed up idle time, loading waits and typing with smooth ramps; off: cut idle time instead (jump cuts). | | `presets` | array | Presets the cut must suit (their length rules apply), e.g. app_preview_iphone, x_16x9, tiktok_9x16. Default: the platform's App Preview + X + TikTok. | | `reset` | boolean | Back to automatic zooms, captions, speed and full length first. | | `slow_mo` | array | Step numbers (from 1) to play at 0.5× from just before the action until its result settles: the hero moment. Replaces the saved list, [] clears it. | | `speed` | array | Manual speed segments (raw take times; replaces the saved list, [] clears it). They win over pacing, eased in and out. | | `style` | object | | | `take_id` **required** | string | Take to render (from end_take). | | `trim` | object | | | `zooms` | array | Replace the automatic zooms (raw take times). | ## `export` Encode a take (as last rendered, else with defaults) for each preset into MP4 files and validate them. App Previews are frameless, 30 fps, H.264 High <= 4.0 with a stereo AAC track and must be 15-30 s; the validator blocks any that break Apple's rules. Free plan: x_16x9 only, watermarked. Returns each file with its measured format. | Parameter | Type | Description | | --- | --- | --- | | `all_sizes` | boolean | With bundle app_store: every accepted screenshot size. | | `bundle` | string | Export a whole folder with README.md (what to upload where): app_store = the platform's App Preview + the required App Store screenshot sizes (exports/app-store); launch = YouTube/Product Hunt, X, TikTok/Reels/Shorts and LinkedIn videos + Product Hunt gallery/thumbnail, Open Graph, X, LinkedIn and square images (exports/launch-kit). Pro. | | `codec` | string | Opt-in codec (default h264). App Previews: prores_422_hq (.mov, large files) or hevc (not on Apple's spec page: warned); other presets: hevc. | | `fps` | integer | 60 for appstore_header / appstore_search_3x2 (Apple allows 30 or 60). | | `headline` | string | With bundle launch: headline on the images (default: the take title). | | `icon` | string | With bundle launch: app icon image for the Product Hunt thumbnail. | | `out_dir` | string | Destination folder (default: the take's exports folder). | | `presets` | array | Output presets: app_preview_iphone, app_preview_iphone_55, app_preview_ipad, app_preview_mac, appstore_header, appstore_search_3x2, x_16x9, x_1x1, x_9x16, tiktok_9x16, youtube_16x9, linkedin_16x9, linkedin_1x1. | | `screenshot_style` | string | With bundle: raw (default) or marketing App Store screenshots. | | `screenshots` | boolean | Also write App Store screenshots from the take's key frames. | | `take_id` **required** | string | Take to export. | ## `import_video` Turn a manual recording (QuickTime, Simulator, Device MCP: ~/Movies/Device MCP/*.mov) into a take: ShowTake finds where the action is (changed areas, scrolls, screen transitions), cuts idle time and plans zooms, then `render` / `export` work as for a filmed take. Without `path` it lists recent recordings. | Parameter | Type | Description | | --- | --- | --- | | `keep_idle` | boolean | Keep the whole recording instead of cutting idle time. | | `path` | string | The .mov/.mp4/.m4v file (omit to list recent recordings). | | `platform` | string | What was recorded (default: portrait = ios, landscape = macos). | | `project` | string | Library project to file the take under (default: the file name). | | `title` | string | Take title (default: the file name). |