VibeDeck Start free trial

Codex Direct Control · macOS only

Run Codex with VibeDeck Direct Control.

Attach a Codex session to VibeDeck's shared local app-server and the deck controls it directly — model carousel (Sol, Terra, Luna), reasoning effort, and config presets, with no /model typing and no picker. Here is why that step exists and the three ways to do it.

This step is required on macOS. Without an attached session, model select, reasoning effort, config presets, and Approve / Deny from the deck do not work for Codex: the keys fall back to opening Codex's own /model picker, and approvals stay in the terminal.

Why Codex needs a shared server Architecture

A plain codex command runs its own private in-process app-server. Nothing outside that process can see or control the session. This is Codex CLI's current architecture — verified against codex 0.144.5 source — not a VibeDeck limitation.

Codex exposes no config file or environment variable to change this default; it is reachable only through command-line flags. We verified this too.

So VibeDeck runs one shared local Codex app-server — a loopback WebSocket bound to 127.0.0.1 only. Any Codex session started against that server becomes controllable from the deck: the model carousel, reasoning effort, and saved config presets all apply directly, with no /model typing and no picker.

Sessions that are not attached still work normally, but the deck cannot control them: model, effort, and preset keys fall back to opening Codex's own /model picker, and Approve / Deny answers stay in the terminal because Codex approvals only reach VibeDeck through the app-server.

Three ways — pick one

Start a controllable Codex session.

All three attach to the same shared server. Putting ~/.vibedeck/bin first on your PATH is the one we recommend: your normal codex command just works, and nothing breaks as ports change.

  1. 1

    Put ~/.vibedeck/bin first on your PATH (recommended)

    VibeDeck installs a codex shim at ~/.vibedeck/bin/codex, identical to vibedeck-codex. Add that directory to the front of your PATH and every codex launch resolves to the shim. The shim execs the real codex by absolute path (no recursion) and prepends --remote only for a bare interactive launch. Subcommands (codex login, codex exec), --version, --help, and a --remote you pass yourself run untouched; every other argument is preserved.

    1. Prepend the directory in ~/.zshrc.

    Add to ~/.zshrc
    echo 'export PATH="$HOME/.vibedeck/bin:$PATH"' >> ~/.zshrc

    2. Reload your shell.

    Reload zsh
    source ~/.zshrc

    3. Verify codex resolves to the shim; it should print ~/.vibedeck/bin/codex.

    Verify the shim
    which codex

    To uninstall, delete that one PATH line and reload. The real codex binary is never modified.

  2. 2

    Alias it

    Point codex at the wrapper so every launch attaches. The wrapper is subcommand-aware — it adds --remote only to interactive launches, and the real codex binary is never modified.

    1. Append the alias to ~/.zshrc.

    Add to ~/.zshrc
    echo 'alias codex="$HOME/.vibedeck/bin/vibedeck-codex"' >> ~/.zshrc

    2. Reload your shell so the alias takes effect in the current terminal.

    Reload zsh
    source ~/.zshrc

    3. Verify that codex now resolves to the wrapper.

    Verify the alias
    type codex

    To uninstall, delete that one alias codex=… line from ~/.zshrc and run source ~/.zshrc again. The real codex binary was never modified.

  3. 3

    Attach manually

    Use this for a one-off session, or when you would rather not touch your PATH or shell config. Pass --remote yourself with the shared server's address. The port below is filled from live status when this page is opened from a VibeDeck key; it can change when the shared server restarts, which is why the PATH method is preferred for everyday use.

    Manual attach
    codex --remote ws://127.0.0.1:<port>

Live status. Checking the shared server…

Going back to plain Codex Revert anytime

The real codex binary is never modified, so reverting only means undoing the one change you made. New sessions then run plain Codex again; the deck keys simply fall back to opening the /model picker.

PATH method: delete the export PATH="$HOME/.vibedeck/bin:$PATH" line from ~/.zshrc, then reload and verify — which codex should print your original install (for example /usr/local/bin/codex or an npm path), not ~/.vibedeck/bin/codex.

Reload and verify
source ~/.zshrc
which codex

Alias method: delete the alias codex=… line from ~/.zshrc, then run the same reload-and-verify.

One session only: no need to revert anything — run the real binary directly for that session, e.g. command codex in zsh, or its full path.

Already-running attached sessions keep working until you close them. To remove every trace, also delete ~/.vibedeck/bin — it holds only the shim and the vibedeck-codex launcher.

Honesty notes Read before relying on it

Direct Control relies on Codex's experimental app-server API, pinned and verified against Codex 0.144.5. A future Codex update may temporarily change that API — until VibeDeck ships an update, the deck keys degrade gracefully to opening Codex's /model picker.

Only sessions started via the shared server are controllable. Existing or plain codex sessions keep the picker; restart them through the wrapper (or the alias) to make them controllable.

Codex Direct Control ships for macOS. Windows support is planned for a future update.

Back to setup