Vizhi for Codex

Physical hardware controls for OpenAI Codex CLI in Apple Terminal or Windows Terminal, on the Logitech MX Creative Keypad. Press a button. Ship code.

Version 1.5.3 · macOS + Windows · Preview

Vizhi for Codex gives Codex CLI the same control surface Claude Console gives Claude Code: live session keys, one-press prompts and git actions, approval keys that grade the risk of what they are approving, native /review, screenshots that land in the running conversation, and fully offline voice. No cloud, no API keys. Everything runs on your machine — see the privacy policy. Not an OpenAI product.

Two rules the product is built around: a key never shows a value the agent did not report, and a press never lands in the wrong window. Every typing key resolves Codex's own Terminal tab and types there, or beeps and types nothing.

Requirements

• A Logitech MX Creative Keypad and Logi Options+ 6.4 or newer.
• Codex CLI installed natively and signed in, usable from Apple Terminal on macOS or Windows Terminal on Windows.
• macOS: Apple Silicon, verified on hardware. Windows: Windows 10 or 11 with Windows Terminal.

Install

1. Install the plugin. From the Logi Marketplace inside Options+ once listed, or by opening a VizhiCodex_1.5.3.lplug4 package: double-click it and Options+ asks to install.
   macOS

   If Gatekeeper blocks the package, right-click it and choose Open, or run xattr -dr com.apple.quarantine VizhiCodex_1.5.3.lplug4 first.

2. Wait about a minute. The 1.5.3 preview registers its own Terminal profile and layout and restarts the plugin service once; Options+ blinks and returns on its own. From 1.6.0 nothing appears until you import the layout, as with Claude Console.
3. Start Codex in Apple Terminal (or Windows Terminal). On macOS, Codex asks you to trust the plugin's hooks; see below.

Import the keypad layout

Needed from 1.6.0, or on 1.5.3 if you prefer to place the keys yourself.

1. Download the layout from the keypad layouts page: VizhiCodex-Keypad.lp5 on macOS, VizhiCodex-Windows.lp5 on Windows.
2. In Logi Options+, open your MX Creative Keypad, open the profile menu (the ⋯ button) and choose Import Profile. Pick the file.
3. It imports as a Terminal profile, five pages deep. Or add Terminal as an application and drag the Vizhi for Codex actions onto it by hand.

Import once. Updating the plugin never touches an imported profile. Do not open the live keys (sessions, Yes, No, Model, Context) in the Options+ icon editor; it freezes them into a snapshot.

Trust the Codex hooks

1. At your next Codex session start you see “Hooks need review — 7 hooks are new or changed”. All seven are this plugin: one per lifecycle event, each running the same one-line launcher, ~/.codex/codex-console/scripts/codex-hook.sh, which writes state files for the keypad and nothing else.
2. Choose Review hooks, confirm, then Trust all and continue. Codex trusts by hash, so this is a one-time step.
3. Start a new session or submit a prompt. The session and approval indicators become live after the first trusted event.

If you choose Continue without trusting, the keys show static labels and no live state. Run /hooks inside Codex to reopen the review. Never start Codex with --dangerously-bypass-hook-trust; it disables the review for everything, not just this plugin.

Permissions

Sessions and answers

Three session keys show a Codex session each: the project folder name and a state bar. Press one to focus its tab and pin the other keys to it, exactly as in Claude Console. Context percentage is read best-effort from Codex's transcript and shows nothing rather than a stale number when the format surprises us. There is no Cost key: Codex reports no spend, and a $0.00 would be indistinguishable from a free session.

Yes and No do two separate things, and only one of them is cross-platform:

• Answering. Pressing Yes or No types the answer into the focused Codex session. Works on macOS and Windows.
• Lighting. The same keys and the session key turn amber when Codex is waiting for an approval and red when the pending command is destructive (git push, rm -rf, sudo and the like). This needs Codex to announce the approval through a hook, so it works on macOS only. On Windows the keys stay dark and answer exactly as well.

Review on page 2 opens Codex's native /review picker: uncommitted changes, against a base branch, or a commit. The Review key on page 3 is different on purpose; it types a structured review prompt into the conversation. Screenshot captures a region with the system picker and types the path into the running session with an instruction to open it; add your question and press Return.

Voice

Everything is transcribed on your machine by whisper.cpp. No audio leaves it.

• Voice. Press, speak, press again. The transcript is typed into Codex's session and submitted.
• Voice Draft. Same flow, but the transcript is only typed, so you can fix a mis-hearing before pressing Return.
• Go to Project (page 4). Say a project name; a new tab opens in that project running Codex.

The first press installs the voice helper, asks for Microphone access, and downloads the base.en speech model once, about 142 MB. That download is the only network request the plugin ever makes, and the file is verified against a known checksum before use.

When it fails, the key says so: Mic denied (allow the voice helper under System Settings → Privacy & Security → Microphone, or on Windows enable microphone access for desktop apps), No speech (it recorded but heard nothing usable), Model loading (the model is still downloading; try again shortly).

Windows notes

• No hooks, no trust prompt. Codex's hook runner creates no process on Windows, an upstream limitation, so the plugin reads Codex's own session transcript (~/.codex/sessions/**/rollout-*.jsonl) to know when a turn starts and ends. It reads only the events it needs and stores none of the conversation.
• No approval lighting. Codex publishes no approval event outside the hook runner, so the keypad declares the capability absent rather than guessing. Yes and No still type answers.
• Windows Terminal is required for tab navigation, session focus, Go to Project and Screenshot. For a classic Command Prompt or PowerShell console, set Settings → System → For developers → Terminal to Windows Terminal and start a new session. Run Codex unelevated; an elevated session cannot be controlled.
• Avoid Windows Terminal's “Rename tab”. Tab switching finds a session by its console, and a renamed tab detaches the label it works through.
• Import the Windows layout, VizhiCodex-Windows.lp5.

Key map

No Tab or Mode keys: Codex has no autocomplete-accept or input-mode cycle, and a key that does nothing reads as broken.

Troubleshooting

The plugin log answers most questions. Attach it when you report a problem.

• macOS~/Library/Application Support/Logi/LogiPluginService/Logs/plugin_logs/VizhiCodex.log
• Windows%LOCALAPPDATA%\Logi\LogiPluginService\Logs\plugin_logs\VizhiCodex.log

Uninstall

1. In Options+, right-click the Vizhi for Codex plugin and choose Uninstall, then delete its Terminal profile.
2. Options+ removes only the plugin. What remains, and how to remove it:
   • The plugin's folder, ~/.codex/codex-console/, with its scripts, the voice helper and the speech model. Delete it.
   • On macOS, the seven hook entries in ~/.codex/hooks.json that run codex-hook.sh. Remove them, or delete the file if it holds nothing else. Codex stops asking about them once they are gone.
   • The state directory /tmp/codex-console/. It is cleared on reboot.

What's new

1.5.3 preview

• Windows install fixed: the sandbox permission grants no longer run inside the service's load budget, so the plugin no longer shows as stuck waiting in Options+.
• Session keys show the project's folder name on Windows.
• The context percentage fills on Windows.
• Tab switching selects by identity, even for two sessions started in the same directory.
• The Screenshot key works on Windows.

Known limitations of the preview

• Windows: no approval lighting (above).
• One console plugin per machine on 1.5.3 (above).
• Layout changes in a later package do not reach an already-imported profile. Delete and re-import the profile after an update that changes the layout.

Free · Privacy · EULA · Report a problem