Documentation

Using VibeSense with Codex

Claude Code remains the default when you run vibesense. Put codex first to select Codex CLI, or use codex-app for the macOS desktop app.

vibesense                         # Claude Code
vibesense codex                   # Codex CLI
vibesense codex --model gpt-5.4   # pass Codex arguments through
vibesense codex --no-game         # controller support without opening a game
vibesense codex-app               # launch and drive the Codex desktop app
vibesense codex-app --auto-play   # keep the game running independently

codex-app is a no-PTY GUI mode. It accepts VibeSense options such as --no-game and --auto-play, not Codex CLI arguments.

First run and hook trust

VibeSense reads Codex’s lifecycle events through four local command hooks:

Codex event	VibeSense behavior
`UserPromptSubmit`	starts or resumes the game
`PermissionRequest`	pauses the game and focuses the approval prompt
`PostToolUse`	resumes the game after the approved tool finishes
`Stop`	pauses the game and focuses that Codex terminal

The hooks are installed in $CODEX_HOME/hooks.json. When CODEX_HOME is unset, the usual location is ~/.codex/hooks.json.

Codex requires you to review new or changed command hooks before they run. On the first launch—or after VibeSense updates a hook definition—open Settings → Hooks in Codex Desktop, inspect the commands, and trust them. Alternatively, open Terminal, run codex, then enter /hooks in Codex CLI. Do not type /hooks in the Desktop composer; the app treats it as a normal prompt. Codex app mode installs VibeSense and OpenMicro command hooks because app automation uses OpenMicro’s shared harness. Repeated launches do not rewrite unchanged definitions.

VibeSense follows Codex’s normal trust flow. It never changes config.toml, bypasses hook trust, or overrides administrator policy.

Codex CLI controls

When Codex is waiting or idle:

D-pad sends arrow keys.
A/✕ sends Enter.
B/○ sends Escape.
Right stick scrolls the terminal.
Y/△ sends a normal space. Voice dictation on that button is a Claude Code feature only.

When Codex is executing, the controller switches to the active game. Menu/Options manually toggles between the game and terminal at any time.

Codex app controls and permissions

When the Codex app is waiting or idle:

D-pad sends arrow keys.
A/✕ accepts with Enter.
B/○ rejects, interrupts, or dismisses with Escape.
Y/△ is hold-to-talk through Codex’s Control+Shift+D dictation shortcut.
Touchpad cycles chats in the current project; L2/LT cycles projects. Actions target the session that Codex brings frontmost.
Continuous right-stick scrolling is unavailable because the shared app harness has no verified equivalent.

On first use, allow the terminal running VibeSense under System Settings → Privacy & Security → Accessibility and Automation so it can control System Events and Codex. The Control+Shift+D Codex dictation shortcut must remain available for push-to-talk. VibeSense delegates these actions to OpenMicro’s exported app harness; it does not copy OpenMicro’s GUI or database automation.

The same hook-driven game handoff, --auto-play policy, game picker, and 750 ms held-input guard apply in app mode.

Multiple sessions

You can run several VibeSense CLI wrappers at once. One process owns the controller and game; each wrapped CLI process carries an opaque instance ID so input and disconnect cleanup stay attached to the correct terminal. Unrelated Codex and Claude sessions are ignored.

Codex app mode must start as the VibeSense host because desktop sessions cannot inherit that wrapper ID. It treats Codex as one shared host: any headerless non-Claude Codex hook can pause the shared game when that session needs attention, including Desktop sessions in another project and unwrapped Codex CLI sessions. Touchpad and L2/LT choose which Desktop session Codex brings frontmost; subsequent controller actions target that frontmost session.

Troubleshooting

If the game does not react to Codex:

Run codex features list and confirm hooks is enabled.
In Codex Desktop, open Settings → Hooks and confirm the VibeSense hooks are trusted and enabled; app mode also requires the OpenMicro hooks. Alternatively, run codex in Terminal and enter /hooks in Codex CLI—not in the Desktop composer.
Check whether local or administrator configuration allows user hooks. Managed environments can restrict Codex to managed hooks only.
If you use a custom CODEX_HOME, confirm hooks.json was created there rather than under ~/.codex.
For app controls, confirm the terminal has Accessibility and Automation permission and Codex still has its Control+Shift+D dictation shortcut.

After you approve a tool, the game may remain paused until that tool finishes. Codex exposes PermissionRequest before the approval prompt and PostToolUse after the tool completes, but no lifecycle event between approval and execution. This is expected; the game resumes on PostToolUse.