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

# Config file

<View title="macOS" icon="apple">
  The `tuple` CLI keeps user-level preferences in `~/.tuple/cli.toml`. If the file exists, the CLI reads it on every invocation.

  The file is created automatically the first time the CLI saves something to it. The containing directory is created with permissions `0700` and the file is written with `0600`.The format is [TOML](https://toml.io).

  ## Top-level keys

  | Key               | Type            | Description                                                                                                                               |
  | ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
  | `default_harness` | string          | Agent key used by `tuple connect` when `--harness` is not passed. Skips the interactive picker.                                           |
  | `mcp_installed`   | table of `bool` | Tracks which agents Tuple has already installed itself into as an MCP server, so it won't re-offer. Keyed by agent name (`claude`, etc.). |
  | `[harness.<key>]` | table           | Per-agent configuration. The `<key>` is the agent name. See [Harness entries](#harness-entries).                                          |

  ## Harness entries

  Each `[harness.<key>]` table describes one agent. The same table is used for three different purposes; which keys you set determines the kind of entry:

  * **Settings-only entry** — set `model`, `reasoning`, or `extra_args` (but neither `command` nor `url`). This applies launch settings to a built-in agent without defining a new agent.
  * **Custom command agent** — set `command` to an argv template. Use `{PROMPT}` as a placeholder for the prompt text. If you omit `{PROMPT}`, the prompt is appended as a final positional argument.
  * **Custom URL agent** — set `url` to a URL template with `{PROMPT}` (URL-encoded) as the placeholder. The URL is opened via the platform opener instead of exec'ing a process.

  `command` and `url` are mutually exclusive on a single entry. If both (or neither) are set on a custom entry, the entry is ignored.

  Custom entries with the same key as a built-in agent (`claude`, `codex`, `cursor`, `copilot`, `opencode`, `pi`, `droid`) shadow the built-in.

  ### Keys

  | Key          | Type            | Description                                                                                          |
  | ------------ | --------------- | ---------------------------------------------------------------------------------------------------- |
  | `command`    | array of string | Argv template. First element is the executable; `{PROMPT}` is replaced with the prompt text.         |
  | `url`        | string          | URL template. `{PROMPT}` is replaced with the URL-encoded prompt and opened via the platform opener. |
  | `model`      | string          | Value substituted into the agent's model flag (`--model`, etc.) at launch time.                      |
  | `reasoning`  | string          | Value substituted into the agent's reasoning-effort flag at launch time.                             |
  | `extra_args` | array of string | Verbatim argv elements inserted before the prompt args on every launch.                              |

  The `model` and `reasoning` values are dropped silently for agents that do not support those flags (`cursor` and `opencode` have no reasoning flag, `droid` has neither). `tuple connect` prints a warning on stderr when this happens.

  `--model` and `--reasoning` flags on `tuple connect` override the saved values for a single invocation.

  ## Example

  ```toml theme={null}
  # ~/.tuple/cli.toml

  # Always launch Claude Code when running `tuple connect` without --harness.
  default_harness = "claude"

  # Agents Tuple has already installed itself into as an MCP server (so it won't re-offer).
  [mcp_installed]
  claude = true
  codex = true

  # Settings-only entry: applies to the built-in claude harness.
  [harness.claude]
  model = "opus"
  reasoning = "high"
  extra_args = ["--verbose"]

  # Custom agent that launches a script with the prompt as its single argument.
  [harness.review]
  command = ["/usr/local/bin/review-agent", "--mode", "interactive", "{PROMPT}"]

  # Custom URL agent that opens a deep link in the browser.
  [harness.cowork]
  url = "https://claude.ai/new?q={PROMPT}"
  ```

  ## What's next

  * [Connect an AI agent](/cli/connect) — the primary consumer of this file.
  * [Command reference](/cli/commands) — every command and flag.
  * [MCP server](/cli/mcp) — register Tuple with an AI coding agent.
</View>