Discord Codex Orchestrator

Local-first Discord bot for running Codex CLI jobs across multiple repo-scoped sessions.

Quick Setup

1. Install prerequisites:

• Bun
• Node.js (required for the PTY bridge helper used by node-pty)
• Codex CLI (codex) available in PATH (or set CODEX_COMMAND)
• A Discord application + bot token
• Bot invited to your server with bot and applications.commands scopes

2. Install dependencies:

bun install

3. Bootstrap local config:

bun run setup

Required values in .env:

• DISCORD_TOKEN
• DISCORD_APP_ID
• Either REPO_ALLOWLIST=/abs/path/repo-a,/abs/path/repo-b or REPO_ALLOWLIST_FILE=./config/repos.local.json

Required values in config/repos.local.json:

• Add at least one allowed repo path to the repos array.

Optional but recommended:

• DISCORD_GUILD_ID for fast guild-only command registration during development
• CODEX_COMMAND and CODEX_ARGS if codex is not directly runnable
• CODEX_APPROVAL_POLICY (on-request default, or never)
• PASTEBIN_DEV_KEY for Pastebin upload support on long outputs
• PASTEBIN_USER_KEY if you want pastes attached to your Pastebin account
• PASTEBIN_PRIVACY (0 public, 1 unlisted, 2 private), PASTEBIN_EXPIRE, PASTEBIN_FORMAT, PASTEBIN_NAME_PREFIX
• PASTEBIN_TRIGGER_CHARS to control when uploads are used

4. Start the bot:

bun run start

Non-Publish Deployment

This project is intentionally private in package.json to prevent accidental npm publishing.
Other users can deploy directly from the repository:

git clone <your-repo-url>
cd discord-codex-orchestrator
bun install
bun run setup
bun run start

For a built entrypoint instead of source execution:

bun run start:dist

Detailed steps: docs/DEPLOY_NON_PUBLISH.md

Usage

1. Run /new repo:<allowed repo name/path> branch:<optional> in a text channel.
2. Open the created thread and run /ask prompt:<text> (thread-only).
3. Use /steer prompt:<correction> in the session thread to course-correct a running/next step.
4. If Codex asks for any interactive input (approval, selection, password, text), respond in the same thread:

• /approve allow:true|false for yes/no approval prompts
• /respond text:"..." submit:true|false secret:true|false for text/password/choice input
• /send-key key:enter|tab|up|down|esc|ctrl-c for control/navigation input

5. Use /updates in the session thread when you want a current progress snapshot (pull-based, low spam).
6. Use /active-threads to get open session thread links with repo/branch/runtime summary.
7. Manage sessions with /list, /switch, /fork, /pause, /resume, /stop, /status.

/ask, /steer, /approve, /respond, /send-key, and /updates are thread-only and do not accept sessionid.

Project Decisions

• Local-first execution: jobs run on your machine; nothing is hosted remotely.
• Safety first: only repos in allowlist are runnable; secret-like text is redacted.
• Session model: one Discord thread maps to one session for clear context boundaries.
• Concurrency model: each session is serialized (queue), while sessions run in parallel.
• Persistence: SQLite (bun:sqlite, WAL mode) stores sessions/messages/jobs/heartbeats and restores sessions after restart.
• Execution model: Bun app runtime with a Node PTY bridge (scripts/codex-pty-proxy.mjs) for reliable node-pty behavior.
• Command model: each /ask or /steer launches a fresh Codex PTY command process (instead of keeping one long-lived PTY shell).
• Interaction model: structured detector (ANSI-stripped + redacted context) captures approval, confirm, choice, password, and text-input prompts.
• Update model: bot avoids continuous output spam; use /updates for on-demand progress and output tail.
• Operator visibility: every reply includes metadata footer (session/runner/thread/repo@branch/status).

Runtime Notes

• Why hybrid (Bun + Node helper)?

• node-pty is not fully reliable under Bun runtime in this workflow, so PTY execution is delegated to Node while the app remains Bun-based.

• Reference: Bun issue #4290

• When to move to full Node runtime:

• If this is production-critical and you want the simplest runtime surface, migrate fully to Node (better-sqlite3 + Node process APIs) and remove Bun runtime coupling.

• If you want minimal migration effort now, keep the current hybrid architecture.

Scripts

• bun run setup
• bun run dev
• bun run start
• bun run start:dist
• bun run build
• bun run typecheck
• bun run lint
• bun run test

Troubleshooting

• ENOENT for codex: set CODEX_COMMAND to the full executable path.
• Slash commands not appearing globally yet: set DISCORD_GUILD_ID for immediate guild registration.
• Long outputs: configure PASTEBIN_DEV_KEY; if Pastebin upload is unavailable, the bot attaches a .md file in-thread as fallback.
• Jobs timing out: raise EXECUTION_TIMEOUT_MS in .env for longer Codex tasks.
• Need interactive approvals/prompts: set CODEX_APPROVAL_POLICY=on-request (default) and restart the bot.
• Startup says another process is running: stop old bun run src/index.ts instances; only one orchestrator instance should run per DB.
• PTY commands appear hung with no output: verify node is installed and reachable in PATH (the PTY bridge runs via Node).