CLIDesktop

Configuration

Agent Relay has three configuration surfaces:

  1. REPL user config at ~/.config/relay/config.toml.
  2. Daemon config at ~/.relay/config.toml.
  3. Repo alert rules at .agent-relay/config/alerts.toml.

There is no general-purpose .agent-relay/config.toml command config in the current CLI, and there is no agent-relay config check command.

REPL user config

The interactive shell reads:

text
~/.config/relay/config.toml

or, when XDG_CONFIG_HOME is set:

text
$XDG_CONFIG_HOME/relay/config.toml

The first-run wizard and /setup write this file. relay install may also update the [handoff] order.

toml
[repl]
default_agent = "claude"
tmux_auto = false
history_size = 1000
theme = "default"
transcript_lines = 5000
auto_compact_chars = 200000
auto_compact_keep_turns = 3
auto_compact_mode = "auto"
last_used_agent = "codex"
 
[repl.env]
extra_forwarded_keys = []
 
[handoff]
order = ["claude", "codex", "gemini", "opencode"]
successor_threshold = 90

Important fields:

KeyMeaning
repl.default_agentAgent selected when the REPL starts.
repl.last_used_agentRemembered automatically after /use or auto-handoff.
repl.tmux_autoWhether the REPL should launch inside tmux by default.
repl.history_sizeNumber of prompt-history entries to retain.
repl.transcript_linesMax lines kept in the in-memory REPL transcript.
repl.auto_compact_charsApproximate saved-context size that triggers auto-compaction; 0 disables it.
repl.auto_compact_keep_turnsNumber of recent turns kept verbatim during compaction.
repl.auto_compact_modeauto, llm, or heuristic.
repl.env.extra_forwarded_keysAdditional environment variables allowed into child agents.
handoff.orderAutomatic fallback chain used after rate limits.
handoff.successor_thresholdPercentage of a usage window at which Relay asks the running agent who should continue; 0 disables the predictive path.

relay install tries to infer handoff.order from detected Claude, Codex, Gemini, and OpenCode CLIs. Override it explicitly when needed:

terminal
relay install --handoff-order claude codex gemini opencode

Daemon config

relay install ensures the daemon config exists at:

text
~/.relay/config.toml

It controls machine-wide daemon behavior:

toml
# agent-relay daemon configuration
 
version = 1
 
[adapters]
claude_code = true
vscode = true
warp = true
pty = true
 
[handoff]
auto = true
notify = true
fallback_chain = []
 
[privacy]
redact_secrets = true
capture_tool_args = false
capture_file_diffs = false
 
[telemetry]
enabled = false
endpoint = "https://telemetry.agent-relay.dev/v1/ingest"
 
[proxy]
enabled = false
listen_port = 9089
confdir = "~/.relay/proxy"

The v0.7 automatic handoff path uses the REPL [handoff].order for live handoff execution. The daemon [handoff].fallback_chain remains part of the daemon schema for daemon-side behavior and compatibility.

Alert rules

Metrics alerts are repo-local and live at:

text
.agent-relay/config/alerts.toml

Create this file when you want alert thresholds for the current repository. The alerts, metrics-tail, and dashboard alert views read from it.

Environment

Child agent environments are filtered. Relay forwards a small base allowlist, RELAY_*, and provider-specific keys for the target agent. Add extra keys under [repl.env] only when an agent truly needs them.

RELAY_LOG_LEVEL controls REPL log verbosity. NO_COLOR is honored by CLI rendering where supported.

Commands that write config

CommandEffect
relay first launchRuns onboarding and writes REPL config.
/setupRe-runs onboarding from inside the REPL.
relay installWrites daemon defaults, installs hooks, and may persist [handoff].order.
relay install --handoff-order ...Explicitly sets the REPL handoff order.
relay install --no-handoff-orderLeaves the REPL handoff order alone.

Next

Installation

Install Agent Relay and run relay install.

Always-on

See how hooks and the daemon trigger automatic handoffs.