CLI 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

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"

…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`
`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.