> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuple.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI agent

<View title="macOS" icon="apple">
  `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](/cli/mcp) 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`](/cli/mcp#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](/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

  ```bash theme={null}
  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:

  1. **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.)
  2. **Picks a harness.** On a TTY you get a picker; with `--harness` it's chosen directly.
  3. **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.
  4. **Launches the harness** with the prompt as its initial message. On Unix, Tuple `exec`s 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:

  ```bash theme={null}
  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](#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.

  ```bash theme={null}
  tuple connect
  tuple connect "review the diff I'm about to open"
  ```

  ### Scripted (`--harness`)

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

  ```bash theme={null}
  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.

  ```bash theme={null}
  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](/cli/config).

  ```bash theme={null}
  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](/cli/commands).

  ### Custom harnesses

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

  ```toml theme={null}
  [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`](/cli/commands#transcription-show-call-id-follow-wait-interval-duration-watch-words-timeout-duration-cursor-tag-with-events-without-speech-with-speech-markers). There are two modes it can use:

  * **`--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.

  ```bash theme={null}
  # 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:

  ```bash theme={null}
  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:

  ```bash theme={null}
  tuple connect --harness codex --model gpt-5 --reasoning high
  ```

  Pipe the prompt into your own agent runner:

  ```bash theme={null}
  tuple connect --print | my-agent-runner --stdin
  ```

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

  ```bash theme={null}
  tuple connect --config
  ```
</View>