Skip to main content
plugin CX Codex

codex-discord-bridge — Claude Code plugin: setup and overview

codex-discord-bridge connects Codex CLI to a Discord bot via a Rust bridge. It lets you assign coding tasks remotely and approve agent actions with message buttons.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-discord-bridge@awesome-codex-plugins
Open on GitHub

What codex-discord-bridge does

The bridge connects a Discord bot to codex app-server over WebSocket using JSON-RPC. Each incoming ping starts or updates a dedicated thread. Agent progress streams directly into a single updating Discord message per turn. When Codex asks to execute a shell command or apply a patch, it sends interactive buttons with a configurable TTL so you can approve operations away from your desk.

Access is restricted to a single controller: the bridge ignores any user whose Discord ID does not match DISCORD_CONTROLLER_USER_ID. If the app-server restarts, a supervisor reconnects with backoff capped at 4s without losing active thread mappings stored in data/state.json.

Running the bridge requires stable Rust, an authenticated Codex CLI session via codex login status, and a Discord bot with the Message Content intent enabled.

What it helps with

  • Run Codex coding tasks remotely from a mobile Discord client
  • Approve agent patches and shell commands using Discord buttons
  • Map Discord discussion threads directly to Codex sessions
  • Maintain agent connections through network drops with automated backoff

Example prompts for the agent

  • Set up the environment using the codex-discord-bridge-setup skill
  • Inspect the bridge status and confirm Discord bot connectivity
  • Run cargo test across the workspace inside a Discord thread

How to install codex-discord-bridge

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-discord-bridge@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-discord-bridge

How to install codex-discord-bridge in Claude Code?

First, register the marketplace source by running /plugin marketplace add hashgraph-online/awesome-codex-plugins. Then install the package with /plugin install codex-discord-bridge@awesome-codex-plugins.

What does codex-discord-bridge do?

It bridges Discord messages to your local Codex CLI session over WebSocket, allowing you to trigger agent tasks and handle approvals from chat.

Can multiple people control the bot?

No, the bridge operates under single-controller mode and only accepts commands from the account specified in DISCORD_CONTROLLER_USER_ID.

Source text

codex-discord-bridge · MIT
# codex-discord-bridge

Control Codex CLI from Discord. A Rust bridge (serenity) that connects a
Discord bot to the Codex app-server over WebSocket, so you can run coding
tasks from your phone.

```
Discord thread  <->  bridge (serenity)  <->  JSON-RPC over WebSocket  <->  codex app-server
```

## How it works

- Message the bot: it starts a Codex thread and streams the agent's output
  back into one live Discord message per turn.
- One Discord thread per Codex conversation. Follow-ups inside the thread
  continue the same conversation instead of starting a new one.
- Approval requests (command execution, patches) arrive as buttons with a
  configurable TTL, so Codex can ask permission mid-task while you are away
  from the desk.
- Autothread mode: each conversation gets its own Discord thread under a
  category you choose, titled from the first message.
- A 20s JSON-RPC keepalive and a bounded supervisor (readiness timeout, backoff
  capped at 4s) reconnect the app-server without dropping your Discord session
  or the thread mappings.

Access is single-controller: only the Discord user id set in
`DISCORD_CONTROLLER_USER_ID` can talk to the bot.

## Requirements

- Rust stable
- A Discord application with a bot token (enable the Message Content intent)
- Codex CLI installed and authenticated (`codex login status`)

## Setup

1. Clone the repo, copy `.env.example` to `.env`, and fill it in:

   ```
   DISCORD_BOT_TOKEN=          # from the Discord developer portal
   DISCORD_APPLICATION_ID=     # your application id
   DISCORD_GUILD_ID=           # your server id
   DISCORD_CONTROLLER_USER_ID= # your Discord user id
   CODEX_COMMAND=codex
   CODEX_APP_SERVER_LISTEN_URL=ws://127.0.0.1:8837
   RUST_LOG=info
   ```

2. Copy `bridge.json.example` to `bridge.json`. The defaults are fine to
   start. Turn on `autoThread.enabled` and set `autoThread.categoryId` if you
   want each conversation in its own thread.

3. Build and run:

   ```
   cargo build --release
   ./target/release/codex-discord-bridge
   ```

4. Invite the bot to your server and send it a message.

## State and logs

- Thread mappings live in `data/state.json`. Stop the bridge before editing
  that file by hand.
- The bridge logs to stdout. `RUST_LOG=debug` in `.env` for verbose output.

## Install as a Codex plugin

This repo ships a plugin manifest (`.codex-plugin/plugin.json`), a setup
skill (`skills/codex-discord-bridge-setup`), and its own marketplace file, so
Codex can install it directly:

```
codex plugin marketplace add yaffalhakim1/codex-discord-bridge
codex plugin add codex-discord-bridge@codex-discord-bridge
```

## Development

- `cargo test` runs the full suite, including reconnect, routing, and stream
  regression tests. State-touching tests use temp dirs via
  `BridgeState::with_path`, and a guard test fails if any test writes the
  production state file.
- `cargo clippy --all-targets -- -D warnings` is kept clean.

## License

MIT

© Yafi Alhakim · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
codex-reset codex-reset is a Claude Code plugin that connects read-only MCP tools for Codex limits. It reports a 24- or 48-hour reset forecast, verified reset records, and service status. CX Codex ★ 1,596repo stars codex-obsidian codex-obsidian connects your agent to local Obsidian vaults via the official desktop CLI. Runs note queries, task rollups, and workspace controls. CX Codex ★ 1,596repo stars codex-mem codex-mem carries compressed project context into later sessions. Use it when you need to pick up work after a session ends or reconnects. CX Codex ★ 1,596repo stars codex-image-plugin codex-image-plugin is a Claude Code plugin for generating and editing raster images through an OpenAI-compatible image API. It supports models, references, and masks. CX Codex ★ 1,596repo stars be-serious The be-serious plugin gives agent text a formal scholarly register and includes a skill for reviewing prose. Use it when plans, explanations, or PR descriptions need a restrained tone. CX Codex ★ 1,596repo stars clera Searches Clera's 210,000+ opted-in candidates, shows the people Clera shortlisted for your roles, and requests intros from the chat. CX Codex ★ 1,596repo stars claude-math Swaps unrendered LaTeX in terminal coding agents for copy-friendly inline Unicode math. CX Codex ★ 1,596repo stars centricmem-skill centricmem-skill is a plugin for Claude Code and Codex that files agent notes as Markdown cards and retrieves them over MCP. A decision made in one client can be found in another. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open