discodex

Discodex (Discord + Codex) is a Discord bot that brings AI-assisted software development into your team's Discord server. It connects OpenAI's Codex to Discord's collaborative infrastructure, letting your entire team interact with AI development sessions in shared, visible threads.

Instead of each developer running AI tools alone in their terminal, Discodex makes agentic coding a team activity. Every prompt, every response, and every code change happens in Discord threads that any team member can watch, contribute to, or learn from.

Core model

• One guild installation (/init) creates:
  • a category (default: discodex-projects)
  • a manager text channel (default: discodex-manager)
• Each project is a forum channel under that category.
• Each forum post/thread is a persistent Discodex conversation.
• Thread runtime parameters are stored in SQLite per Discord thread.

Slash commands

• /init
• /thread settings view
• /thread settings set
• /thread pause
• /thread resume
• /thread reset_context
• /manager debug mode:on|off
• /auth login force:<true|false>
• /auth logout
• /auth status
• /access status
• /access role set group:<admin|user> role:<@role>
• /access policy view
• /access policy set capability:<...> mode:<on|off>
• /access policy reset

Access model

Warning

Deploy this bot only for trusted users. Even with container isolation, Codex auth credentials are still accessible to the codex users, and bot-driven runs may expose sensitive files if your runtime/policy settings allow it.

• Exactly two bot groups: admin and user.
• No per-user custom permission and no feature-set system.
• Bot permission does not modify Discord channel/category permission overwrite.
• Admin is determined by:
  • guild owner
  • Discord Administrator / ManageGuild
  • mapped discodex-admin role
• User capabilities are guild-wide policy toggles for the mapped discodex-user role.
• Default user policy after /init:
  • thread_chat = on
  • thread_settings_view = on
  • auth_manage_self = on
  • all others off
• If user lacks bot permission for thread_chat, bot does not enqueue Discodex run and sends a short warning message that auto-deletes.

Manager channel behavior

In manager channel, admins can use natural language requests such as:

• create a project named api with a new git repository
• create a project named api by cloning https://github.com/org/repo.git
• create worktree feature-x for project api on branch feat/feature-x
• list projects
• archive project api

Manager responses are generated via Discodex structured output schema. Mutating actions are proposed first, then executed only after confirm button click.

Environment variables

See .env.example.

Required:

• DISCORD_TOKEN

Common runtime:

• CODEX_BIN
• CODEX_ENV_PASSTHROUGH (optional comma-separated whitelist additions)
• DISCODEX_BOT_WORKSPACE
• DISCODEX_WORKSPACE_ROOT
• DISCODEX_STATE_DB_PATH
• LOG_LEVEL
• LOG_DIR
• DISCORD_PROGRESS_UPDATES_ENABLED
• DISCORD_PROGRESS_UPDATE_INTERVAL_MS
• DISCORD_PROGRESS_MAX_RECENT_EVENTS
• DISCORD_REPLY_SEND_INTERVAL_MS
• DISCODEX_CATEGORY_NAME
• DISCODEX_MANAGER_CHANNEL_NAME
• DISCODEX_ADMIN_ROLE_NAME
• DISCODEX_USER_ROLE_NAME
• DISCODEX_MULTI_USER_ENABLED
• DISCODEX_USE_SYSTEM_CODEX_HOME
• DISCODEX_CODEX_HOME_ROOT
• DISCODEX_CODEX_HOME_SHARED (JSON array string)
• MANAGER_ACTION_EXPIRES_MS
• DISCORD_UNAUTHORIZED_NOTICE_DELETE_MS
• DISCORD_UNAUTHORIZED_NOTICE_COOLDOWN_MS

Optional default Discodex runtime values:

• DEFAULT_MODEL
• DEFAULT_REASONING_EFFORT
• DEFAULT_APPROVAL_POLICY
• DEFAULT_SANDBOX_MODE
• DEFAULT_WEB_SEARCH_MODE
• DEFAULT_NETWORK_ACCESS_ENABLED

Codex Home Profiles

• Default mode (DISCODEX_MULTI_USER_ENABLED=false) always uses the default profile.
• Multi-user mode (DISCODEX_MULTI_USER_ENABLED=true) maps profile id to Discord user id.
• Profile homes:
  • default: <DISCODEX_CODEX_HOME_ROOT>/default
  • user: <DISCODEX_CODEX_HOME_ROOT>/user/<discord-user-id>

System mode matrix:

• DISCODEX_USE_SYSTEM_CODEX_HOME=true and multi-user disabled:
  • Discodex does not pass CODEX_HOME to SDK and uses system default Codex home.
• DISCODEX_USE_SYSTEM_CODEX_HOME=true and multi-user enabled:
  • Discodex still uses profile homes above, and shared entries symlink to system base ($CODEX_HOME or ~/.codex).

Shared/auth rules:

• Every entry in DISCODEX_CODEX_HOME_SHARED is symlinked from profile home to base home.
• Existing conflicting files/directories/symlinks are force-replaced.
• default/auth.json is symlinked to base/auth.json.
• user/<id>/auth.json must be a local file; symlink is rejected as invalid.
• If user auth file does not exist, Discodex does not create a placeholder file.

Auth commands:

• /auth ... commands are guild-only and always reply as ephemeral messages.
• /auth ... commands are enabled when DISCODEX_MULTI_USER_ENABLED=true or DISCODEX_USE_SYSTEM_CODEX_HOME=false.
• In multi-user mode, /auth targets user/<discord-user-id>/auth.json.
• In single-user managed mode (DISCODEX_MULTI_USER_ENABLED=false, DISCODEX_USE_SYSTEM_CODEX_HOME=false), /auth targets default/auth.json (shared credential for all users).
• /auth commands are disabled only when DISCODEX_MULTI_USER_ENABLED=false and DISCODEX_USE_SYSTEM_CODEX_HOME=true.

Development

pnpm install
pnpm run prisma:migrate:deploy
pnpm run validate
pnpm start

pnpm start does not run migrations. Run pnpm run prisma:migrate:deploy before starting the bot.

If you are upgrading from an older build that used the internal migration runner, run one of:

• reset the SQLite database file and then run pnpm run prisma:migrate:deploy
• baseline manually with Prisma migrate resolve before deploy

Docker

cp .env.example .env
# fill DISCORD_TOKEN in .env
docker compose up --build -d

• The container runs prisma migrate deploy before starting the bot.
• Persistent runtime state is stored in ./.data on the host.

Prisma

Database access is managed through Prisma Client.

pnpm run prisma:migrate:deploy
pnpm run prisma:generate
pnpm run prisma:format
pnpm run prisma:studio

This project uses Prisma 7 driver adapters:

• Schema datasource URL is configured in prisma.config.ts
• Runtime client uses @prisma/adapter-better-sqlite3
• SQLite file path defaults to DISCODEX_STATE_DB_PATH from .env (or can be overridden by DATABASE_URL)

Codex CLI env is whitelist-based. The bot passes a safe env map via CodexOptions.env and does not allow SDK default full process.env inheritance.

Diagnostics

pnpm run prisma:studio

Notes

• Managed repositories are stored at <DISCODEX_WORKSPACE_ROOT>/<workspace-id>/repository.
• Managed worktrees are stored at <DISCODEX_WORKSPACE_ROOT>/<workspace-id>/worktree/<worktree-name>.
• Project threads show Discodex intermediate progress in a single throttled status message to avoid Discord rate-limit pressure.