Octo-dex

Octo-dex is a local-first desktop companion for Codex. It observes Codex activity, normalizes local signals into internal events, and turns the current state into a live widget with the Dex mascot, usage metrics, dashboard views, and local diagnostics.

Preview

Thinking	Coding

Idle	Executing

What Octo-dex Does

• Observes local Codex activity through providers controlled by the Rust Core.
• Normalizes source-specific signals before they reach the UI.
• Displays Codex state in a compact, movable widget with configurable always-on-top behavior.
• Shows usage, limits, quota reset timing, recent history, and diagnostics in the dashboard.
• Keeps the WebView away from unrestricted filesystem, shell, SQLite, and ~/.codex access.
• Persists local settings in SQLite.
• Falls back gracefully when live signals are unavailable.

States And Behaviors

Dex currently represents core states such as:

• idle
• thinking
• coding
• executing
• testing
• waiting
• success
• error
• interrupted
• sleeping

It also includes visual modifiers and behaviors for situations such as:

• on-fire
• maxed-out
• poke
• celebrate
• critical usage
• cached/stale data
• multiple sessions

Stack

• Tauri 2
• Rust
• React
• TypeScript strict
• Vite
• pnpm
• Cargo
• SQLite

Development

Install dependencies:

pnpm install

Run the desktop app in development mode:

pnpm --filter @octodex/desktop tauri dev

Development mode keeps a terminal attached for logs. To test the app without that terminal, create a release-like build and open the generated executable:

pnpm --filter @octodex/desktop tauri build

Generated executable:

target/release/octo-dex.exe

Generated installers:

target/release/bundle/nsis/Octo-dex_0.1.0_x64-setup.exe
target/release/bundle/msi/Octo-dex_0.1.0_x64_en-US.msi

Validation

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm rust:fmt
pnpm rust:clippy
pnpm rust:test
pnpm --filter @octodex/desktop tauri build

Release

The project includes a GitHub Actions workflow for tag-based releases.

Recommended tag for the first version:

v0.1.0

When a v*.*.* tag is pushed to GitHub, the workflow builds the Windows app and creates a draft GitHub Release with the installers attached.

See docs/RELEASE.md for details.

Project Status

Phases 0 through 9 have been approved by the developer. Phase 10, Hardening + v1.0, is currently READY FOR DEVELOPER VALIDATION.

Documentation

Main versioned documents:

• SPEC
• ARCHITECTURE
• ROADMAP
• INSTALLATION
• RELEASE
• RELEASE_NOTES
• CONTRIBUTING