codex-devtools

Desktop inspector for Codex session data.
Browse conversations, search messages, and analyze agent activity across sessions.

---

Quick start

Requires:

• Bun 1.2+
• Node.js 20+ (for tooling)
• pnpm 10

git clone https://github.com/gulivan/codex-devtools.git
cd codex-devtools
corepack enable
pnpm install
pnpm dev

This launches the Electrobun desktop app.

Run from npm/bunx:

bunx codex-devtools
# or
npx codex-devtools

Standalone mode

Run as an HTTP server without desktop shell:

pnpm standalone

Or from the CLI entry:

codex-devtools --web

Default standalone host: http://localhost:3456.

Build

pnpm build          # vite renderer + electrobun desktop build
pnpm dist           # stable electrobun package for current host platform

Notes:

• Electrobun builds are host-platform only.
• dist:mac, dist:win, and dist:linux are host aliases to pnpm dist.

Environment variables

Variable	Default	Description
CODEX_SESSIONS_PATH	~/.codex/sessions	Path to Codex sessions directory
HOST	0.0.0.0	Standalone server host
PORT	3456	Standalone server port
CODEX_DEVTOOLS_DEFAULT_MODE	desktop	Set to web to default CLI to standalone mode

Scripts

Script	Description
pnpm dev	Build renderer and run Electrobun dev mode
pnpm dev:hmr	Run Vite + Electrobun together
pnpm build	Build renderer + Electrobun desktop bundle
pnpm standalone	Build renderer and run standalone HTTP mode
pnpm dist	Stable Electrobun build (host platform)
pnpm test	Run tests (Vitest)
pnpm lint	Run ESLint
pnpm typecheck	TypeScript type checks

License

MIT