Agent Relay

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"]

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.

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.