CLI adapters

Installed hooks and plugins

relay install wires shipped CLI integrations when their tools are detected:

Agent	Integration
Codex	`Stop` hook that scans final messages and transcript tails for OpenAI rate-limit signals.
Gemini	`Notification` hook that scans notification payloads for Google quota/rate-limit signals.
OpenCode	Relay-owned config plugin that forwards `session.error`, `message.updated`, and `session.status` events to `relay hook opencode-event`.

The OpenCode plugin is removed by relay uninstall only when it contains Relay's ownership marker, so user-owned plugin files are preserved.

PTY wrapper

terminal

relay wrap <command> [args...]

PTY-wraps any CLI agent — codex, aider, gemini-cli, sgpt, llm, anything that runs in a terminal — and instruments its stdout for rate-limit patterns without disturbing colours, prompts, or ^C.

Example

terminal

relay wrap aider --model gpt-4
relay wrap codex --model anthropic/claude-opus-4-7
relay wrap gemini chat
relay wrap opencode

Indistinguishable from running the underlying command directly. Signals forward, ANSI escapes pass through, terminal resize works.

Optional aliases

Add to ~/.zshrc / ~/.bashrc:

terminal

alias aider="relay wrap aider"
alias codex="relay wrap codex"
alias gemini="relay wrap gemini"
alias opencode="relay wrap opencode"

…and forget about Relay. Every invocation is captured.

What's detected

Signal	Source
`started` / `stopped`	Spawn + exit lifecycle.
`rate_limited`	Line-pattern scan against known provider strings — `anthropic-ratelimit-*`, `rate_limit_exceeded`, `RESOURCE_EXHAUSTED`, `HTTP/1.1 429`.
Exit reasons	`done` (rc=0), `error` (rc≠0), `rate_limited`, `user_quit` (SIGINT), `crashed`.

For lossless rate-limit detection use proxy mode — that reads the actual response headers instead of guessing from stdout.

Agent slug

The slug shown in events comes from argv[0]:

Command	Slug
`aider`	`aider`
`codex`	`codex`
`gemini`	`gemini-cli`
`opencode`	`opencode`
`claude`	`claude-code`
Unknown	`cli:<basename>`

Trailing version suffixes like aider-1.2.3 are stripped — relay wrap aider-1.2.3 still produces slug aider.

Platform support

POSIX (macOS + Linux). Windows ConPTY support lands alongside the binary distribution; relay wrap raises a clear NotImplementedError on Windows today.

Source

src/agent_relay/adapters/pty_wrapper.py and src/agent_relay/adapters/output_classifier.py.