relayforge 0.1.0

Route chat channels to agent targets.

Relayforge

Relayforge routes chat channels to agent targets.

The first provider is Discord. The first targets are a Codex app-server binding and a Codex JSONL fallback inbox. The package is Python and PyPI-ready, with provider-neutral core types so Slack, WhatsApp, and other agent APIs can be added later.

Install

After the package is published:

pip install relayforge

The installed CLI command is relayforge.

Installed wheels add a small managed Relayforge block to:

• ~/.codex/AGENTS.md
• ~/.claude/CLAUDE.md

Set RELAYFORGE_SKIP_AGENT_GUIDES=1 before starting Python with the installed package on sys.path to skip this.

From this checkout:

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

Configuration

{
  "channels": [
    {
      "name": "rohan-codex",
      "provider": "discord",
      "id": "1520170530148192466",
      "owner": "rohan"
    }
  ],
  "bindings": [
    {
      "name": "rohan-almanac-main",
      "source": "rohan-codex",
      "target": "codex-app-server",
      "codexThreadId": "replace-with-codex-thread-id",
      "cwd": "/Users/rohan/Desktop/Projects/almanac",
      "machine": "replace-with-hostname",
      "transport": "codex app-server --config mcp_servers={} --listen stdio://"
    }
  ],
  "routes": [
    {
      "channel": "rohan-codex",
      "target": "codex-jsonl",
      "inboxPath": ".relay/rohan-codex-inbox.jsonl"
    }
  ]
}

Each founder can use the same Discord bot token with a different named channel. A binding delivers to that founder's Codex thread on the right machine. A route keeps JSONL fallback delivery available when the direct target fails.

See docs/channels.md for the multi-founder pattern. See docs/research/codex-thread-routing-2026-06-26.md for the Codex thread binding direction.

Commands

export DISCORD_BOT_TOKEN=...

relayforge init --config relay.config.json
relayforge channel-set --name rohan-codex --provider discord --id 1520...
relayforge route-set --channel rohan-codex --target codex-jsonl --inbox-path .relay/rohan-codex-inbox.jsonl
relayforge binding-set --name rohan-almanac-main --source rohan-codex --target codex-app-server --codex-thread-id 019f... --cwd /Users/rohan/Desktop/Projects/almanac --transport "codex app-server --config mcp_servers={} --listen stdio://"
relayforge check --config relay.config.json
relayforge listen --config relay.config.json
relayforge listen --config relay.config.json --include-bots --max-messages 1 --timeout 20
relayforge check --config relay.config.json --json
relayforge channels --config relay.config.json
relayforge routes --config relay.config.json
relayforge bindings --config relay.config.json
relayforge codex-smoke --binding rohan-almanac-main --message "smoke test"
relayforge binding-send --binding rohan-almanac-main --message "reply in Discord"
relayforge send --channel rohan-codex --message "hello"
relayforge read --channel rohan-codex --limit 10
relayforge inbox --path .relay/rohan-codex-inbox.jsonl --limit 10
relayforge inbox --path .relay/rohan-codex-inbox.jsonl --cursor .relay/rohan.cursor.json --ack

Raw Discord channel IDs work for read and send even before a config file exists. Named channels require the config.

The listen command uses Discord Gateway events. That means Discord pushes new messages to this process instead of the process polling the channel.

By default, Discord bot-authored messages are ignored to avoid loops. Use --include-bots only for controlled smoke tests or deliberate bot-to-agent routing.

codex-smoke sends a synthetic message through a configured Codex app-server binding. Use it only with a rollout-backed Codex thread that is safe to receive a test turn.