Migrate Tuple CLI and MCP integrations

This page is the migration entry point for Tuple alpha testers and their agents. Give your agent this page with the files you want updated. It covers the Transcription CLI generation and the Capture CLI generation. Last verified: September 9, 2026, against installed macOS 3.2.0 and a separately built Capture-generation CLI. Select the contract exposed by your installed app and binary.

Identify the installed contract

Before editing an integration:

Resolve the exact executable your script or MCP configuration launches. Keep the CLI paired with its app and environment.
Record the app version and build. On macOS, read the app bundle’s Info.plist. The Transcription-generation CLI rejects --version.
Read root and nested help from that executable. For MCP, initialize that server and read tools/list, resources/list, resources/templates/list, and prompts/list. Tool availability can depend on the session.
Select the matching column below. Update only to commands and schemas the installed executable exposes. If the app and CLI disagree, resolve the installation mismatch before testing actions.

For a standard macOS installation:

ls -l /usr/local/bin/tuple
/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' /Applications/Tuple.app/Contents/Info.plist
/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' /Applications/Tuple.app/Contents/Info.plist
/Applications/Tuple.app/Contents/SharedSupport/bin/tuple --help

Adjust the bundle path if you use a different installation. An MCP initialization response’s server version identifies the server implementation, not the Tuple app release.

Contract	How to identify it	Instructions to use
Transcription generation	Root help lists `transcription`; `transcription show --help` lists `--follow`, `--wait`, and `--with-events`.	Keep the legacy commands until the installed app and CLI support Capture. The baseline inspected for this guide is macOS 3.2.0, build `3.2.0-2026-08-12-9d2e82a561`.
Capture generation	Root help lists `capture`; nested help exposes `capture show`, `capture follow`, `capture next`, `connect prompt`, and executable `screen`.	Apply the Capture column and verify its behavior below. Use the command reference and release notes for the installed release.

Detect the command contract instead of assuming a minimum version from this table. A root command’s presence alone does not prove a flag, MCP tool, or app capability is available.

Update commands and defaults

Every command below starts with tuple. Preserve the exact executable path in scripts and bundled integrations.

Legacy command or option	Capture-generation replacement	Change and required action
`transcription start`, `transcription stop`	`capture start`, `capture stop`	Rename. Capture owns the call record, including transcript, events, content, stored screen media, and annotations.
`transcription show <call>`	`capture show <call>`	Rename and default change. Read all categories unless you explicitly exclude some.
`transcription show <call> --follow --with-events`	`capture follow <call>`	Split into a dedicated reader. Events are included by default.
`transcription show <call> --wait`	`capture next <call>`	Split and semantic change. The caller owns the delivery checkpoint.
`--cursor my-agent` on a legacy wait reader	`--cursor <record-id>` on `capture follow` or `capture next`	Semantic change. A named server-side read position is not a record ID. Start catch-up without a cursor and save the highest delivered positive ID.
`--interval 60s` on a transcript reader	`--batch 60s`	Rename for batching. Use only on `follow` or `next`.
`--watch-words`	Repeatable `--wake-on`	Each value is one literal phrase. A comma stays inside that phrase. Use with `--batch`.
`transcription watch get`, `path`, `set`	Reader-owned `--wake-on @<file>` or literal phrases	Shared state removed. A continuous follower reloads only its own specified files. `next` reads them once per invocation.
`--with-events`, `--with-speech-markers`	Complete reads, or `--exclude events,content` for transcript-only output	Default and category change. Category selection does not reproduce every legacy record-type filter.
`--without-speech`, `--without-chat`	Select categories, then filter individual record types in your consumer if needed	Semantic change. `--exclude transcript` removes the transcript category, not just finalized speech. Preserve chat and other records your task needs.
`transcription list`, `search`, `delete`	`capture list`, `search`, `delete`	Rename. Deletion also removes retained media. Test reads first and preserve confirmation for deletion.
`transcription export <dir> --format md`	`capture export <file> --as markdown`	Destination and format change. One artifact contains all selected calls.
Export `--format ndjson`	Export `--as jsonl`	Artifact format rename. Global `--format json` controls the receipt, not the artifact.
`transcription set-title`, `set-summary`	`call edit <call> --title ... --summary ...`	Relocation and merge. Set only fields you intend to change.
`call current`	`call show`	Rename and broader lookup. A call selector can identify an active or ended call.
`call hang-up`	`call leave`	Rename.
`call add`, `call remove`	`call participants add`, `call participants remove`	Relocation.
`call mute`, `call unmute`	`call mute`, `call unmute`	Unchanged CLI commands. MCP names change separately below.
Top-level `reaction`	`call react`	Relocation. Read help for supported sounds.
`contacts list <query>`	`contacts list --query <query>`	Positional query removed.
`state --follow`	`state follow`	Dedicated stream command. Bounded summaries are the default; `--raw` requests the full payload.
`screen capture -o image.jpg`	`screen -o image.jpg`	Executable command. Without `-o`, it saves an automatically named JPEG.
`connect --print` or non-terminal implicit prompt output	`connect prompt`	Explicit command. Root `connect` launches an agent.
`connect --config`	`connect configure [harness]`	Explicit configuration command.
Global `--format default` or `--format table`	`--format text`	Format change. Text is the default; scripts must request JSON explicitly.
Global `--format ndjson`	`--format json`	JSON Lines is the stream encoding, not a global format name.

The inspected 3.2.0 root help does not list machines. On a Capture-generation installation that exposes it, use machines list and pass its machine UUID to call start <person-or-machine-id>. Keep person-name resolution separate from machine IDs. Contacts and rooms retain their command groups. Verify filters through nested help. Notifications use notifications send, ask, list, and cancel; replace legacy notifications list --follow with notifications follow. Replace contacts list --follow with contacts follow. Rooms use rooms follow for updates and rooms show for one room. Verify each command separately instead of replacing flags globally. Terms such as sessions, --session, review/headless modes, and mcp serve can occur in older skills but are absent from the inspected baseline’s public command tree. Remove those assumptions. Use Call selectors, connect prompt for instructions, and tuple mcp as the server entry point. A Capture recording selector is --recording <uuid>; it is distinct from a connected client’s session identity. In cli.toml, remove the obsolete mcp_installed bookkeeping key. Keep client registration in the client’s MCP configuration. For requested ongoing participation, per-harness attention defaults use [harness.<key>.attention] with batch and wake_on; saving those defaults does not start a reader. See configuration fields.

Preserve Capture meaning and delivery

capture show --format json returns a finite sequence of JSON Lines. capture follow --format json and capture next --format json also emit JSON Lines. Parse each stream line separately and distinguish durable records from framing. The categories are transcript, events, and content. Replace any conversation category assumption with the appropriate supported category. The record type transcription_finished still identifies finalized speech; a product command rename does not rename record types. For an explicitly requested ongoing task:

Keep one reader for the selected call. Its first read supplies catch-up, so a separate initial snapshot can duplicate context.
Deliver durable records to the model or destination. Save the highest positive record id only after that delivery succeeds.
Resume with that ID, the same call or recording selector, and the same exclusions. Retain the prior checkpoint after a delivery failure.
Handle kind: "status" separately from durable records. Carry terminal framing to the task controller so it can stop at call end. Neither framing nor an ephemeral id: 0 advances the checkpoint.
Stop a call-specific reader at call_ended. recording_ended means Capture stopped and may restart within the call. A follower without a call selector stays open across calls, so use it only when the user’s task covers those calls.

# First read for an explicitly requested ongoing task:
tuple --format json capture next a1b2c3d4 --batch 5s

# After the model receives records through ID 42:
tuple --format json capture next a1b2c3d4 --cursor 42 --batch 5s

Replace the sample call and record IDs with observed values. Persist the returned checkpoint only after delivery succeeds. A verification read is still an undelivered read: it must not advance the saved checkpoint. If delivery succeeds but saving fails, the next read can replay those records; make your destination idempotent or deduplicate by call and record ID. A repeated batch command without an updated checkpoint can replay catch-up. A shell loop that discards stdout does not deliver context to an agent. An empty first CLI batch still needs --cursor 0 on the next invocation to wait for records instead of repeating immediate catch-up. Keep the prior cursor after later empty batches. --since selects time-based catch-up. It is not a delivery checkpoint. --until belongs to bounded show, not live readers. For Capture exclusions, keep at least one category. Exports take a file destination. They preserve the previous destination if no calls match and replace it only after a complete artifact is ready. Create a private temporary directory for verification instead of overwriting an existing export.

tuple capture export ./call.jsonl --call a1b2c3d4 --as jsonl --format json
tuple capture export ./call.md --call a1b2c3d4 --as markdown --exclude events,content

Each JSON Lines artifact record includes call_id so a multi-call export remains attributable.

Update MCP configuration and allowlists

Keep tuple mcp as the server command and point it at the matching bundled executable. Reconnect the client after changing configuration, then refresh discovery. Keep the client-specific server prefix when replacing allowlisted tool suffixes.

Legacy MCP name	Capture-generation route	Change
`start_transcription`, `stop_transcription`	`start_capture`, `stop_capture`	Rename and complete Capture ownership.
`get_transcription`, `get_transcription_events`, `transcription_show`	`get_capture`	Merge into a bounded Call plus records. Preserve needed categories with `exclude`.
`transcription_list`, `transcription_search`	`list_captures`, `search_captures`	Rename. Validate argument and result schemas.
`transcription_export`	`export_captures`	Rename and artifact change: replace `dir` with `destination`, and keep the MCP `format` field with values `jsonl`, `markdown`, or `text`.
`set_call_title`, `set_call_summary`	`update_call`	Merge. Use `call_id` and only the metadata fields you intend to update.
`capture_screen`	`get_screen`	Rename. Omit `at` for live pixels; provide `at` and `call_id` for a stored moment.
`get_active_call`	`get_state` for orientation; `get_capture` for a bounded Call and its records	Removal and task-specific replacement.
`end_call`	`leave_call`	Rename.
`mute`, `unmute`	`mute_microphone`, `unmute_microphone`	Rename.
`connect` tool	Read `tuple://agent/guide`, then the topic needed for the task	Removed tool. The `connect` prompt remains capability-dependent and provides context once. Neither route begins monitoring.
`transcription_set_watch_words`	`wake_on` on advertised `next_capture`; app-owned `set_attention` where registered	Shared mutation removed. Do not add a tool the server doesn’t advertise.
State, transcript, event, notification, and archive resource aliases and subscriptions	Bounded tools and `tuple://capture/{callId}`	Removed subscriptions and duplicate resources. Explicit ongoing delivery uses an advertised reader.

Resource migrations are explicit reads:

Legacy resource URI	Capture-generation read
`tuple://state`	`get_state`; use entity tools for full collections
`tuple://call/{callId}/transcription` and `.json`	`get_capture` with `call_id`, or `tuple://capture/{callId}`
`tuple://call/{callId}/events` and `.json`	`get_capture` with `exclude: ["transcript", "content"]`
`tuple://call/{callId}/stream` and `.json`	`get_capture` for a snapshot; advertised `next_capture` for requested ongoing delivery
`tuple://call/{callId}/notifications` and `.json`	`list_notifications` with `call_id`
`tuple://transcription/calls` and `.json`	`list_captures`
`tuple://transcription/call/{callId}/transcript` and `.json`	`get_capture` with `call_id`

Remove resource subscriptions and their re-read callbacks. A bounded snapshot does not replace a subscription’s ongoing behavior; implement explicit reader ownership for a task that needs it. find_discussion and summarize_call prompts remain available. The connect prompt appears when the app permits live-call pull. Read their current argument schemas. Use ordinary search terms in examples instead of teaching agents raw database query syntax. Resources include tuple://agent/guide, tuple://agent/guide/{topic}, and tuple://capture/{callId}. Topics include live-call, call-content, past-calls, communication, safety, connection, troubleshooting, and automation. The app’s managed mount also supplies managed-agent. When advertised for an attached session, next_capture returns a batch with call_id, records, cursor, and terminal. Omit cursor for initial catch-up. After delivery, repeat with the returned call and cursor. If initial catch-up is empty, cursor: 0 starts waiting. Stop at terminal call_ended; retain the reader across recording_ended. Use batch, timeout, and wake_on according to the advertised schema. Agent messaging and managed attention depend on session capabilities. Refresh discovery when it changes. The app owns managed mode and its delivery loop. Reading managed-agent or changing an allowlist does not make an attached agent managed.

Check scripts, skills, and prompts

Search the files you own, including AGENTS.md, CLAUDE.md, skills, launch scripts, MCP configurations, and allowlists:

rg -n 'transcription|capture_screen|get_active_call|screen capture|mcp serve|connect --print|connect --config|hang-up|watch.words|--session|--format (table|default|ndjson)' .

Review every match in context. Preserve valid record types and any intentional legacy compatibility branch. For each edited integration:

Pin its executable and app environment. Keep separate verified branches if it supports both generations.
Replace command names, flags, destinations, structured argument fields, and response parsers together.
Make a one-time request finish after its bounded reads. Start one ongoing reader only for an explicit follow-along request.
Remove named active/passive/watch modes and unsolicited polling from prompts. Use the installed shared guides for participation instructions.
Preserve confirmation and user intent for call actions, notifications, exports, and deletion.

Verify behavior before declaring migration complete

Run these checks with the matching app and CLI. Report actual exit codes, stderr, parsed results, and any check you could not exercise.

Check	Expected result
Nested help for every changed command and discovery for every allowlisted tool	The exact spelling, flag, and input schema exists in the installed environment.
`tuple state --format json`	One parseable JSON value with app/call orientation. Default output is text.
`tuple capture show <stored-call> --format json`	A finite JSON Lines sequence containing the selected call’s complete records. Exclusions remove only the requested categories.
A JSON Lines export to a fresh file in a private temporary directory	One artifact, attributable records, and a separate command receipt. An unmatched selection leaves an existing destination untouched.
A call-specific batch reader followed by resume	Delivered records do not replay after their checkpoint. A simulated delivery failure resumes from the preceding checkpoint and recovers undelivered records.
A call-specific follower through Capture stop/restart and call end	Recording end does not end the task; call end does. Check cross-call following separately if your integration uses it.
`tuple screen -o <temporary-file>` and stored `--call` plus `--at`	JPEG output when media exists. Preserve reported timing/annotation caveats. Missing stored media is a data-availability error.
Invalid input, missing call, and unavailable capability	Non-zero CLI failure or MCP error; no success-shaped result is treated as completion.
Give an agent only this page and representative legacy files	It updates the script, skill, and allowlist, then passes the applicable execution checks without extra migration instructions.

The removed screen_share_recording product flag is separate from macOS Screen Recording permission. Capture owns stored screen media. Historical selectors remain discoverable even when a call has no stored video. Use the CLI reference, Connect guide, and MCP reference for ongoing use after migration.

Getting Started

Pairing with Tuple

Managing Your Account

Team Management

Application Preferences

Tuple CLI

Triggers

Troubleshooting

Migrate Tuple CLI and MCP integrations

Identify the installed contract

Update commands and defaults

Preserve Capture meaning and delivery

Update MCP configuration and allowlists

Check scripts, skills, and prompts

Verify behavior before declaring migration complete

​Identify the installed contract

​Update commands and defaults

​Preserve Capture meaning and delivery

​Update MCP configuration and allowlists

​Check scripts, skills, and prompts

​Verify behavior before declaring migration complete

Identify the installed contract

Update commands and defaults

Preserve Capture meaning and delivery

Update MCP configuration and allowlists

Check scripts, skills, and prompts

Verify behavior before declaring migration complete