CodexChat

Local-first Discord gateway for running Codex from Discord while keeping code, secrets, policy, approvals, audit logs, and execution on your Mac.

macOS-first Foundation Release. Not a SaaS runner. Not a thin bot wrapper. BYO Discord bot; Admin UI stays localhost by default.

Current Status

Foundation is working end-to-end on macOS:

• Discord bot token stored in macOS Keychain.
• Discord guild slash command registered.
• Text fallback works for plain /codexchat ... messages.
• Real Discord text task → local CodexCliAdapter → Discord reply verified.
• Each task runs in an isolated git worktree/snapshot with timeout, output cap, cleanup, and Codex workspace-write sandbox flags.
• Policy checks run before execution; high-risk tasks create approvals instead of executing.
• Approval list/approve/deny are available in Admin and Discord slash/text commands.
• Discord task commands create or reuse a task thread; run records persist guild/channel/thread ids, replies go to the task thread, and Admin links back to the thread.
• Text fallback polls configured channels plus active threads whose parent channel is allowed.
• launchd service installed as ai.codexchat.gateway and runs start --agent codex.
• Admin UI shows service health, safe config, approvals, Recent Runs, run events, Discord thread links, Audit Log, and a local service smoke button.

Quick Start

npx --yes [email protected] install
npx --yes [email protected] codexchat init
npx --yes [email protected] codexchat doctor
npx --yes [email protected] service:install
npx --yes [email protected] service:status

Manual run:

npx --yes [email protected] start -- --agent codex

Discord Usage

Slash command:

/codexchat status
/codexchat task instruction:<task>
/codexchat approvals
/codexchat approve approval_<id>
/codexchat deny approval_<id>

Plain-text fallback:

/codexchat status
/codexchat task Print exactly CODEXCHAT_SMOKE_OK and do not modify files.
/codexchat approvals
/codexchat approve approval_<id>
/codexchat deny approval_<id>

Text fallback is configurable under discord.textFallback:

textFallback:
  enabled: true
  pollIntervalMs: 10000
  initialLookbackMs: 2000
  maxSeenMessages: 1000

Discord Threads

CodexChat supports Discord task threads:

• /codexchat task ... in a normal text channel creates a public task thread and sends task progress/results there.
• /codexchat task ... inside an existing thread reuses that thread.
• Run records store guildId, channelId, and threadId.
• Admin Recent Runs shows an Open Discord thread link when a run has a thread binding.
• Text fallback polls active threads whose parent channel is allowed.

Smoke test real thread permissions:

npx --yes [email protected] exec tsx src/cli/index.ts discord-thread-smoke

Quality Gates

npx --yes [email protected] typecheck
npx --yes [email protected] lint
npx --yes [email protected] test
npx --yes [email protected] security:scan
npx --yes [email protected] arch:check
npx --yes [email protected] build
npx --yes [email protected] release:check
npx --yes [email protected] pack:check
npx --yes [email protected] codexchat doctor --architecture

Automation-only Discord smoke tests (no human tester needed):

npx --yes [email protected] exec tsx src/cli/index.ts discord-thread-smoke
npx --yes [email protected] exec tsx src/cli/index.ts discord-approval-smoke
npx --yes [email protected] exec tsx src/cli/index.ts discord-inbound-smoke
npx --yes [email protected] exec tsx src/cli/index.ts discord-slash-smoke
npx --yes [email protected] exec tsx src/cli/index.ts discord-poller-smoke

discord-inbound-smoke does not require a human tester. It simulates inbound text commands for status, task, approvals, approve, and deny, including duplicate suppression, bot-message suppression, user/channel allowlists, parent-thread allowlist handling, and task thread binding.

discord-slash-smoke simulates slash interactions for status, task, approvals, approve, and deny, including deferReply/editReply, task thread binding, and approval state transitions.

discord-poller-smoke simulates REST text fallback polling with no Discord network calls. It verifies allowed parent channels, active thread filtering, after cursor construction, chronological processing of Discord's newest-first message pages, thread parent binding, and cursor advancement.

Release Readiness

npx --yes [email protected] release:check
npx --yes [email protected] exec tsx src/cli/index.ts release-readiness

The readiness check validates required release docs, config examples, quality scripts, package metadata, package contents posture, and committed secret patterns. pack:check runs npm pack --dry-run and verifies required package files plus forbidden runtime/secret patterns. release:check includes both readiness and pack audit.

The package is now in publishable posture (private=false). Before an actual npm publish, rerun the full release checklist and confirm package ownership/name availability in the target npm registry.

See CHANGELOG.md and docs/RELEASE_CHECKLIST.md before any public release. Rotate the Discord bot token first if it was ever pasted into chat, screenshots, issues, shell history, or logs.

Why CodexChat?

CodexChat lets you operate Codex from Discord while keeping code, secrets, policy, logs, and execution on your machine.

P0 Principles

• macOS-first, locally testable.
• BYO Discord Bot.
• AgentAdapter contract from day one.
• Admin UI from day one.
• Policy, sandbox, approvals, and audit from day one.