🚀 Relay-agent

A reliable delegation broker for AI CLIs (Claude, Codex, Antigravity) on Windows, Linux, and macOS.

Note on Guarantees: Relay-agent validates the execution and delivery contract (result-file creation, encoding, schema, artifact paths, and process completion). It does not verify the factual accuracy or reasoning quality of the AI-generated content.

Note on Cross-platform: The test suite runs on Windows, macOS, and Linux across Python 3.11–3.13 on every commit. All three providers have passed a deep audit against their real CLIs on Windows 11 — Claude Code 2.1.218, Codex CLI 0.144.3, and Antigravity 1.1.5 (see docs/KNOWN_LIMITATIONS.md). Real provider CLIs have not yet been field-validated on Linux or macOS, where CI exercises mocks only. Validate each worker you intend to use with relay doctor --worker <worker> --deep, and run it again whenever the underlying CLI is upgraded.

📑 Table of Contents

✨ Key Features
📦 System Requirements
🚀 Installation & Verification
💡 Usage & Task Files
🤖 OpenClaw / Hermes AI & Multi-Worker Delegation
🔍 Model Discovery & Limitations
📄 JSON Result Contract
➕ Adding New Workers (relay add-agent)
⚙️ Configuration & Security
🧹 Cleanup and Retention
📚 Documentation

✨ Key Features

Relay-agent is a reliable task broker designed to connect your always-on AI agents with powerful coding CLIs.

🤖 Supports Three Built-in CLIs: Natively supports task delegation to Claude Code, Codex CLI, and Antigravity.
➕ Extensible via add-agent: Register any external AI CLI that follows the standard worker contract (relay add-agent <id>).
🤝 Designed for Agent Delegation: Always-on AI agents (like Hermes or OpenClaw) can hand off complex, long-running tasks to Relay-agent and retrieve the final results asynchronously.
📂 Dedicated Workspaces: Each job runs from a separate Relay-agent managed workspace. This reduces accidental file collisions but is not a complete OS sandbox. Unattended use requires a dedicated low-privilege OS account.
🗄️ Persistent History: Every delegated job's metadata, errors, and output paths are recorded in a local SQLite database.
✅ Validated Delivery Contract: Relay-agent checks result-file creation, encoding, JSON/TXT structure, artifact paths, and process completion before publishing outputs.

📦 System Requirements

Windows 11, Linux, or macOS
Python 3.11+
At least one installed and logged-in worker CLI:
- claude
- codex
- agy — optional, requires additional security verification
For Hermes Unattended Execution: A dedicated low-privilege OS account is strictly required.

🚀 Installation & Verification

1. Clone & Install

git clone https://github.com/miter37/Relay-agent.git
cd Relay-agent

relay.pyz is a build artifact and is not stored in the repository, so the installer builds it on first run. This needs no network access and takes a second. To build it yourself instead:

python build_release.py

Prefer not to build? Download relay.pyz and SHA256SUMS.txt from the latest release, verify the checksum, and place relay.pyz in this directory before running the installer.

Windows (PowerShell):

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install_windows.ps1

Linux / macOS:

chmod +x scripts/install_unix.sh
./scripts/install_unix.sh

2. Verify Workers

relay init
relay doctor --worker claude --deep
relay doctor --worker codex --deep

3. Antigravity Setup (Optional & Advanced)

Because Antigravity has strong permission bypass capabilities, it requires explicit opt-in after you have verified your OS-level isolation:

relay doctor --worker antigravity --deep
# ONLY run these if you have configured OS-level isolation:
relay config set workers.antigravity.security_verified true
relay config enable-worker antigravity

💡 Usage & Task Files

Short Requests (Inline)

Use direct task arguments for simple, short requests:

relay "Investigate today's major AI semiconductor news" --worker codex

Note on fallback: --worker codex means "Try Codex first, but fallback if it fails." If you want only Codex, use --worker codex --no-fallback.

Structured Requests (Task Files)

For long or structured tasks (recommended for agents), use a UTF-8 Markdown task file:

Windows (PowerShell):

relay run `
  --task-file "D:\RelayInput\request.md" `
  --worker claude `
  --format json `
  --machine

Linux / macOS:

relay run \
  --task-file "/home/relay/input/request.md" \
  --worker claude \
  --format json \
  --machine

Attachments

Relay-agent can pass files along with the prompt (must be inside permitted input directories for Hermes):

relay run `
  --task-file "D:\RelayInput\analyze.md" `
  --attach "D:\RelayInput\report.pdf" `
  --attach "D:\RelayInput\data.xlsx" `
  --worker claude `
  --format json

🤖 OpenClaw / Hermes AI & Multi-Worker Delegation

By registering the skill skills/hermes-relay/SKILL.md (Skill name: use_relay_agent) in your AI environment, OpenClaw or Hermes AI can use Relay-agent to delegate complex tasks and aggregate results.

Example: "Ask Claude, Codex, and Antigravity to propose an architecture for a cross-platform job queue, then compare their trade-offs."

To achieve this without falling back to a different worker on failure, the agent submits 3 separate asynchronous jobs with --no-fallback and --caller hermes.

⚠️ Important on --request-id: The request ID is an idempotency key. It must uniquely identify one logical request (e.g., <conversation-id>-<task-id>-<worker>). Reusing the same ID returns the existing cached job, even if the task file has changed.

relay submit \
  --task-file "task.md" \
  --worker claude \
  --format json \
  --request-id "jobqueue-arch-claude" \
  --caller hermes \
  --no-fallback \
  --machine

relay submit \
  --task-file "task.md" \
  --worker codex \
  --format json \
  --request-id "jobqueue-arch-codex" \
  --caller hermes \
  --no-fallback \
  --machine

relay submit \
  --task-file "task.md" \
  --worker antigravity \
  --format json \
  --request-id "jobqueue-arch-agy" \
  --caller hermes \
  --no-fallback \
  --machine

(Note: If you omit --no-fallback, a failure in Claude might silently trigger a Codex retry, muddling which AI actually answered.)

Asynchronous Flow:

Parse the job_id from the submit JSON receipt.
Wait for completion: relay wait <job_id> --machine
Get final receipt: relay result <job_id> --machine
Read the actual output file from the result_path provided in the receipt.

🔍 Model Discovery & Limitations

Relay-agent discovers models using worker-specific methods. Codex and Antigravity can provide account-aware catalogs when supported. Claude Code does not expose a complete non-interactive model-list API, so its results may include configured or known model candidates rather than a definitive account-level list.

relay models
relay models --worker codex --refresh

Checking Model Availability (model-check): Check whether a model is listed or can be minimally verified. Claude uses a small inference probe, while Codex and Antigravity currently check catalog membership.

relay model-check --worker claude --model sonnet --machine

⚠️ Warning on Claude Probe: A failed Claude model check (ok: false) does not strictly mean the model name is invalid. Authentication expiration, quota exhaustion, rate limits, or network timeouts will currently all return false.

📄 JSON Result Contract

When requesting --format json, the file written to your --out path will follow this structure:

{
  "schema_version": "1.0",
  "status": "complete",
  "answer": "The requested analysis...",
  "sources": ["https://example.com"],
  "uncertainties": ["Market volatility makes this unpredictable"],
  "missing_items": [],
  "artifacts": [
    {
      "name": "chart.csv",
      "relative_path": "path/to/chart.csv",
      "description": "Generated comparison chart"
    }
  ]
}

Important: The Relay-agent receipt status (e.g., completed) indicates successful CLI execution. The internal JSON status (e.g., complete or partial) indicates the AI's self-reported success on the actual task logic.

➕ Adding New Workers (`relay add-agent`)

The three built-in workers (claude, codex, antigravity) cover most users, but any external AI CLI that follows the standard Relay worker contract can be registered interactively:

relay add-agent opencode

The wizard prompts for:

Worker ID (used as the relay.toml key, e.g. opencode, grok-build)
Display name
Executable path or name on PATH
Command template using placeholders such as {cli}, {request_file}, {result_file}, {artifact_dir}, {model}
Default model
Optional advanced settings (max turns, extra args, env vars, timeout)
Whether to enable the worker after registration

Once all inputs are collected, Relay runs doctor --deep as a health check. If the check fails, nothing is written to relay.toml — fix the issue and retry, or pass --skip-health-check to persist the registration anyway.

# Verify after registration
relay doctor --worker opencode --deep
relay run --worker opencode "Hello"

# Non-interactive registration (e.g. from a setup script)
RELAY_ADD_AGENT_ID=opencode \
RELAY_ADD_AGENT_COMMAND=opencode \
RELAY_ADD_AGENT_COMMAND_TEMPLATE='{cli} exec --prompt {request_file} --output {result_file}' \
relay add-agent --yes

See relay add-agent --help for all options and the full list of RELAY_ADD_AGENT_* environment variables.

⚙️ Configuration & Security

Security & Unattended Execution: To use --caller hermes, the operator must configure a low-privilege account and ACL isolation. After securing the host, acknowledge it:

relay security --machine
relay config set service_isolation_acknowledged true

Set default workers and fallbacks:

relay config set default_worker claude
relay config set fallback_order codex,antigravity

🧹 Cleanup and Retention

Relay-agent automatically deletes expired internal staging and workspace directories according to job status:

Completed: 7 days
Partial: 14 days
Failed: 30 days
Cancelled: 14 days
Orphan workspaces: 7 days

Note: Automated cleanup applies to Relay-agent's internal workspaces. Final result files and artifacts delivered to the configured --out and --artifacts destinations are not automatically deleted.

relay cleanup --status

📚 Documentation

For deeper details, consult the docs/ folder:

Built with ❤️ for reliable AI delegation.

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github		.github
config		config
docs		docs
mocks		mocks
relay		relay
scripts		scripts
skills/hermes-relay		skills/hermes-relay
tests		tests
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SECURITY.md		SECURITY.md
build_release.py		build_release.py
manual.md		manual.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🚀 Relay-agent

📑 Table of Contents

✨ Key Features

📦 System Requirements

🚀 Installation & Verification

1. Clone & Install

2. Verify Workers

3. Antigravity Setup (Optional & Advanced)

💡 Usage & Task Files

Short Requests (Inline)

Structured Requests (Task Files)

Attachments

🤖 OpenClaw / Hermes AI & Multi-Worker Delegation

🔍 Model Discovery & Limitations

📄 JSON Result Contract

➕ Adding New Workers (`relay add-agent`)

⚙️ Configuration & Security

🧹 Cleanup and Retention

📚 Documentation

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🚀 Relay-agent

📑 Table of Contents

✨ Key Features

📦 System Requirements

🚀 Installation & Verification

1. Clone & Install

2. Verify Workers

3. Antigravity Setup (Optional & Advanced)

💡 Usage & Task Files

Short Requests (Inline)

Structured Requests (Task Files)

Attachments

🤖 OpenClaw / Hermes AI & Multi-Worker Delegation

🔍 Model Discovery & Limitations

📄 JSON Result Contract

➕ Adding New Workers (relay add-agent)

⚙️ Configuration & Security

🧹 Cleanup and Retention

📚 Documentation

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

➕ Adding New Workers (`relay add-agent`)