Config file

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.

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

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

# ~/.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 — the primary consumer of this file.
Command reference — every command and flag.
MCP server — register Tuple with an AI coding agent.

Getting Started

Pairing with Tuple

Managing Your Account

Team Management

Application Preferences

Tuple CLI

Triggers

Troubleshooting

Top-level keys

Harness entries

Keys

Example

What’s next

​Top-level keys

​Harness entries

​Keys

​Example

​What’s next

Top-level keys

Harness entries

Keys

Example

What’s next