Connect an AI agent

tuple connect brings an AI coding agent into your current Tuple call. It’s the fastest way to put Claude Code, Codex, Cursor, Copilot, opencode, Pi, Droid, or your own custom agent on the call with you — no MCP install, no hand-written prompt.

When to use it

You’re on a call and want an AI agent listening alongside you to help debug, make tickets on your behalf, or answer questions you ask out loud.
You want a scripted way to launch an agent into a call from a keybinding or workflow runner.
You’re an agent that needs to drop into the active call yourself — pipe tuple connect --print into your own context.

If you only want the agent to control Tuple programmatically (start calls, list contacts, search past transcripts), use the MCP server instead. connect is for live, in-call participation.If you’re already running an MCP-aware agent and just want to attach it to the current call, invoke the /tuple:connect slash command instead — it builds the same sidekick context without launching a new harness.

Prerequisites

The Tuple desktop app is running and signed in. See the CLI overview for install and authorization steps.
The harness you pick is on your PATH (e.g. claude, codex, cursor-agent). tuple connect doesn’t install the harness for you.

Quick start

tuple connect                          # interactive picker
tuple connect "help me debug this bug" # picker, with a starting purpose
tuple connect --harness claude         # skip the picker
tuple connect --print                  # write the prompt to stdout
tuple connect --config                 # edit per-agent settings

The first run on a TTY walks you through choosing a default harness and (optionally) saving a model and reasoning effort to ~/.tuple/cli.toml.

How it works

When you run tuple connect, Tuple:

Resolves call state. If you’re not on a call, you can start one or join a room. If transcription isn’t running, the interactive picker offers to start it so the agent has something to follow. (In --harness and --print modes, transcription is not started for you.)
Picks a harness. On a TTY you get a picker; with --harness it’s chosen directly.
Builds a context prompt that includes the active call’s ID, the participants, the harness’s model/reasoning settings, and a tutorial section teaching the agent the relevant tuple commands — how to follow the live transcript, capture the screen, post a notification card to ask you a yes/no question, and search past calls.
Launches the harness with the prompt as its initial message. On Unix, Tuple execs the harness so it inherits your terminal directly.

The generated prompt embeds state guidance, so even if the call state changes (you join a different room, transcription is stopped), the agent has instructions for recovering on its own.

Supported harnesses

Key	Display name	How it’s launched
`claude`	Claude Code	`claude -- <prompt>`
`codex`	OpenAI Codex	`codex -- <prompt>`
`cursor`	Cursor Agent	`cursor-agent <prompt>`
`copilot`	GitHub Copilot	`copilot -i <prompt>`
`opencode`	opencode	`opencode --prompt <prompt>`
`pi`	Pi	`pi <prompt>`
`droid`	Factory Droid	`droid <prompt>`

You can also point --harness at any executable path:

tuple connect --harness /usr/local/bin/my-agent

Custom harnesses, including URL-based deep-link agents (e.g. Claude Cowork), can be defined in ~/.tuple/cli.toml — see Custom harnesses below.

Modes

tuple connect picks a mode automatically, but you can force one:

Interactive (default on a TTY)

Shows the harness picker, resolves call state, then launches.

tuple connect
tuple connect "review the diff I'm about to open"

Scripted (`--harness`)

Skips the picker. Useful for keybindings, scripts, or trigger handlers.

tuple connect --harness claude
tuple connect --harness claude --model sonnet --reasoning high

--model and --reasoning override any saved per-harness settings for this launch. Unsupported flags for a harness produce a stderr warning and are ignored.

Print (`--print` or non-TTY)

Builds the prompt and writes it to stdout instead of launching anything. Use it when you’re piping the prompt into an agent yourself, or when an agent invokes tuple connect from inside its own session to learn about Tuple’s CLI surface.

tuple connect --print > /tmp/prompt.txt
tuple connect --print --harness claude       # include the claude-specific section

Combining --print with --harness includes the per-harness guidance in the output but does not launch the harness.

Config (`--config`)

Opens an interactive TUI for editing the model, reasoning effort, and extra arguments saved per harness in ~/.tuple/cli.toml. You can read more about the CLI config file.

tuple connect --config

--config uses the same settings walkthrough as the interactive tuple connect flow: for harnesses with a known model or reasoning option set (such as Claude Code’s opus / sonnet / haiku), you get a constrained picker with an Other… escape hatch into free text. Harnesses without a known option set fall through to a free-text prompt. After the walkthrough, --config asks whether to make the harness your default before saving and exiting — it never launches the agent.

Flags

Flag	Description
`--harness <name>`	Builtin key, custom name, or executable path. Skips the picker.
`--print`	Write the context prompt to stdout instead of launching an agent.
`--model <name>`	Model to pass to the harness’s model flag. Overrides the saved per-harness model for this launch.
`--reasoning <level>`	Reasoning effort to pass to the harness’s effort flag. Overrides the saved per-harness value.
`--config`	Open the TUI to edit per-agent settings saved to `~/.tuple/cli.toml`.

Global flags work as documented in the command reference.

Custom harnesses

Add a [harness.<name>] entry with command (an argv template) or url (a deep-link template). Both use {PROMPT} as the placeholder.

[harness.my-agent]
command = ["my-agent", "--initial-message", "{PROMPT}"]

[harness.cowork]
url = "https://claude.ai/cowork?message={PROMPT}"

Custom names appear in the picker alongside the builtins, and you can target them with --harness my-agent.

Following the transcript

The prompt generated by tuple connect teaches the agent to follow the live call with tuple transcription show. It can use two modes:

--follow — continuous stream of records (NDJSON with --format json), one line per speech segment or event. Best for harnesses that have a per-line wake mechanism (such as Claude Code’s Monitor).
--wait — block until the next batch of transcript arrives, print it, then exit. Loop it in the foreground to follow a call from any harness, without burning tokens on every utterance.

# Foreground follow loop the agent can run in any harness:
while tuple transcription show --wait --interval 60s --watch-words "claude,hey claude"; do
  : # process the batch the loop just printed
done

--interval gathers transcript for up to the given duration before flushing, so the agent wakes once per minute (or whatever you choose) instead of on every utterance. --watch-words flushes the batch early — and ends the relaxed interval — when a configured word or phrase is spoken, so the agent responds immediately when you address it by name.

Examples

Drop Claude Code onto the active call with a starting task:

tuple connect --harness claude "summarize what we decide in the next 10 minutes"

Launch Codex with a specific model and reasoning level from a keybinding:

tuple connect --harness codex --model gpt-5 --reasoning high

Pipe the prompt into your own agent runner:

tuple connect --print | my-agent-runner --stdin

Edit which model each harness uses without touching cli.toml by hand:

tuple connect --config

Getting Started

Pairing with Tuple

Managing Your Account

Team Management

Application Preferences

Tuple CLI

Triggers

Troubleshooting

When to use it

Prerequisites

Quick start

How it works

Supported harnesses

Modes

Interactive (default on a TTY)

Scripted (`--harness`)

Print (`--print` or non-TTY)

Config (`--config`)

Flags

Custom harnesses

Following the transcript

Examples

​When to use it

​Prerequisites

​Quick start

​How it works

​Supported harnesses

​Modes

​Interactive (default on a TTY)

​Scripted (--harness)

​Print (--print or non-TTY)

​Config (--config)

​Flags

​Custom harnesses

​Following the transcript

​Examples

When to use it

Prerequisites

Quick start

How it works

Supported harnesses

Modes

Interactive (default on a TTY)

Scripted (`--harness`)

Print (`--print` or non-TTY)

Config (`--config`)

Flags

Custom harnesses

Following the transcript

Examples