better-codex

better-codex is a Codex session hub: a web UI plus a local backend that supervises codex app-server to manage multiple accounts, sessions, reviews, and analytics in one place.

Features

• Multi-account hub with session list, threads, and model switching.
• Reviews view backed by Codex review mode events.
• Analytics + search (local SQLite indexes).
• Zero-config better-codex launcher that boots backend + UI.

Project Layout

• apps/backend Bun + Elysia hub server, Codex app-server supervisor.
• apps/web React UI (Vite).
• scripts/ launcher scripts for local dev.
• bin/ CLI wrappers (better-codex).

Requirements

• Bun: https://bun.sh
• Codex CLI (codex) available in PATH.
• Node 18+ for the npm package wrapper.

Install (npm)

npm i -g better-codex

Run (zero-config)

better-codex

Optional:

better-codex web --open

Run from Source

export PATH="$(pwd)/bin:$PATH"
better-codex

Manual Dev (backend + UI)

cd apps/backend
bun install
bun run dev

cd apps/web
VITE_CODEX_HUB_URL=http://127.0.0.1:7711 \
VITE_CODEX_HUB_TOKEN=<token from backend log> \
bun install
bun run dev

Configuration

Backend env vars

• CODEX_HUB_HOST (default 127.0.0.1)
• CODEX_HUB_PORT (default 7711)
• CODEX_HUB_TOKEN (auto-generated by launcher)
• CODEX_BIN (default codex)
• CODEX_FLAGS, CODEX_FLAGS_JSON
• CODEX_APP_SERVER_FLAGS, CODEX_APP_SERVER_FLAGS_JSON
• CODEX_HUB_DEFAULT_CWD (default repo root)
• CODEX_HUB_DATA_DIR (default ~/.codex-hub)
• CODEX_HUB_PROFILES_DIR (default ~/.codex/profiles)
• CODEX_HUB_DEFAULT_CODEX_HOME (default ~/.codex)

Web env vars

• VITE_CODEX_HUB_URL (default http://127.0.0.1:7711)
• VITE_CODEX_HUB_TOKEN

Troubleshooting

• bun: command not found: install Bun and reopen your terminal.
• codex: command not found: install Codex CLI and ensure it is in PATH.
• Port already in use: pass --backend-port or --web-port.
• UI can’t connect: token mismatch or backend not running; restart and copy the token.