codex-matrix-style

Crash-safe Matrix appearance for Codex desktop on macOS.

This project gives Codex a green-on-black "terminal" style without patching app bundles.

Safety model

This tool is designed to avoid the crash loops caused by app.asar edits.

• It does not modify /Applications/Codex.app/Contents/Resources/app.asar.
• It writes user preferences only in ~/.codex/.codex-global-state.json.
• It applies Matrix look by runtime CSS injection through Codex's local DevTools endpoint.
• It includes rollback commands.

If Codex updates, you rerun one command.

What you get

• Matrix-like UI colors (#00ff00 on black)
• Matrix-like terminal palette
• Monogreen-first editor token appearance (with error/warn preserved)
• Persistent runtime re-apply daemon while Codex is open

Requirements

• macOS with Codex desktop installed (default /Applications/Codex.app)
• Node.js >= 18
• Terminal access

Install

git clone https://github.com/benzionb/codex-matrix-style.git
cd codex-matrix-style
npm install

Quick start (recommended)

./bin/codex-matrix-style start

This does:

1. Sets safe user appearance/font settings.
2. Restarts Codex with --remote-debugging-port=9333.
3. Injects Matrix CSS at runtime.
4. Starts a background daemon that keeps the style applied.

Verify

./bin/codex-matrix-style status

Expected values:

• runtime daemon running: true
• debug endpoint reachable: true
• matrix style detected: true

Daily usage

No launchd/autostart layer is included in this repo.

If you open Codex normally later (for example via Spotlight), run this again:

./bin/codex-matrix-style start

Rollback

./bin/codex-matrix-style rollback

Rollback does:

• stop daemon
• remove runtime style (if debug endpoint is reachable)
• restore saved settings

Main commands

./bin/codex-matrix-style start
./bin/codex-matrix-style apply --restart-with-debug
./bin/codex-matrix-style apply --no-daemon
./bin/codex-matrix-style status
./bin/codex-matrix-style rollback
./bin/codex-matrix-style stop-daemon

Shorthand wrappers also exist:

./bin/codex-matrix-apply
./bin/codex-matrix-status
./bin/codex-matrix-rollback

Configuration

Environment variables:

• CODEX_APP_PATH (default: /Applications/Codex.app)
• CODEX_MATRIX_PORT (default: 9333)
• CODEX_MATRIX_BASE_THEME (default: houston)
• CODEX_MATRIX_HOME (default: ~/.codex/matrix-style)
• CODEX_MATRIX_POLL_MS (default: 1500)

Example:

CODEX_MATRIX_PORT=9334 ./bin/codex-matrix-style start

State and logs

• State: ~/.codex/matrix-style/state/state.json
• Daemon log: ~/.codex/matrix-style/state/runtime-daemon.log
• Daemon PID: ~/.codex/matrix-style/state/runtime-daemon.pid

Troubleshooting

If status says debug endpoint is unreachable:

open -na /Applications/Codex.app --args --remote-debugging-port=9333
./bin/codex-matrix-style apply

If you see no Matrix styling after startup:

./bin/codex-matrix-style inject
./bin/codex-matrix-style status

More details: docs/TROUBLESHOOTING.md

How it works

High-level design is documented in:

• docs/HOW_IT_WORKS.md
• docs/SAFETY.md