> ## 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

> Give an agent Tuple call context, request help once, or explicitly ask it to follow along.

<View title="macOS" icon="apple">
  `tuple connect` launches an AI coding agent with context for Tuple. Use `tuple connect prompt` to give that context to an agent that's already running.

  Connecting or reading a guide supplies instructions. For a one-time question, the agent reads the relevant context, answers, and finishes. Ask explicitly when you want ongoing participation.

  ## Prerequisites

  The Tuple desktop app must be running and signed in. Follow the [CLI setup and authorization steps](/cli/overview). The agent you choose must be installed separately and available on your `PATH`.

  ## Choose a call and an agent

  ```bash theme={null}
  tuple connect
  tuple connect "help me understand this error"
  tuple connect --harness claude
  tuple connect --call a1b2c3d4
  ```

  An active call supplies live context. An ended call supplies historical context. `--call` selects either by ID. An unknown call ID returns an error.

  If you run `tuple connect` in a terminal without a default agent or `--harness`, a one-step picker asks which agent to use. Tuple saves only that choice as the default, then continues the original command with its purpose and `--call` selection. Canceling the picker leaves the configuration unchanged and does not contact the app or launch an agent.

  Passing `--harness` skips first-run setup. Outside a terminal, specify `--harness` or run `tuple connect configure` in a terminal first.

  | Flag | Purpose |
  | - | - |
  | `--harness <name>` | Built-in agent, custom name, or executable path. Skips the picker. |
  | `--call <id>` | Select an active or ended call. |
  | `--model <name>` | Override the saved model for this launch. |
  | `--reasoning <level>` | Override the saved reasoning setting for this launch. |

  Run `tuple connect --help` for the installed command's options. Use [the migration guide](/cli/migration) when updating an existing integration.

  ## Give an existing agent context

  ```bash theme={null}
  tuple connect prompt
  tuple connect prompt --call a1b2c3d4
  tuple connect prompt "explain the error we discussed"
  ```

  This command writes instructions to stdout without launching an agent. Load the output into your agent's context. For a runner that accepts a prompt on stdin:

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

  Agents can read the embedded guide directly:

  ```bash theme={null}
  tuple agent guide
  tuple agent guide live-call
  tuple agent guide past-calls
  ```

  Choose `connection` for call connectivity or quality problems, and `troubleshooting` for tool failures or missing call content. The [MCP server](/cli/mcp#resources) exposes the same guidance as resources.

  ## Configure launches

  ```bash theme={null}
  tuple connect configure
  tuple connect configure claude
  ```

  Use this explicit configuration flow to choose a default agent and edit advanced launch settings in [`~/.tuple/cli.toml`](/cli/config). It exits after configuration without launching the agent. Built-in agents include Claude Code, Codex, Cursor, Copilot, opencode, Pi, Droid, and Prime Agent.

  Command-based agents can save model, reasoning, and additional argument settings when supported. URL-based agents ignore these settings, so the configuration flow skips those questions for them.

  You can define a custom executable using an argument template:

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

  Then launch it with `tuple connect --harness my-agent`. See [custom harness settings](/cli/config#harness-entries) for URL templates and additional arguments.

  ## Ask an agent to follow along

  For ongoing help, give the agent an explicit task and stopping condition, such as “Follow this call and summarize decisions when it ends.” The agent needs an environment that can continue working between messages. For more example prompts, see [Ways to use Capture](/pairing-with-tuple/ways-to-use-capture#during-a-call).

  <Note>
    In our testing, the harnesses with the best support for following a call in real time are [Claude Code](https://claude.com/product/claude-code) and [Pi](https://pi.dev/). [Codex](https://chatgpt.com/codex) and [Claude desktop](https://claude.com/download) are less reliable, and support fluctuates as models and harnesses evolve. We're exploring ways to make this experience more consistent while still giving you the freedom to use the models and harnesses you want. [Get in touch](mailto:support@tuple.app) if you want to learn more!
  </Note>

  An attached agent owns one reader and its delivery checkpoint. It can use a continuous reader:

  ```bash theme={null}
  tuple --format json capture follow a1b2c3d4 --batch 5s
  ```

  Or request one batch at a time:

  ```bash theme={null}
  tuple --format json capture next a1b2c3d4 --batch 5s
  ```

  The first read includes catch-up. If the first batch is empty, use `--cursor 0` to wait on the next read. After the records reach the model, repeat with `--cursor <record-id>` using the highest delivered positive ID. Keep the same call selector and exclusions. A failed delivery keeps the previous checkpoint so the next read can recover the records. See [Capture readers](/cli/commands#capture-follow-call-id) for framing, timeouts, and wake phrases.

  With MCP, use `next_capture` only when the server advertises it. Its response and checkpoint rules are documented in [live Capture delivery](/cli/mcp).

  A Tuple-managed agent receives context from the app. Use the app-provided tools and `managed-agent` guide for that session. The app owns its ongoing delivery; an attached agent remains attached when it reads a guide.
</View>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.