VibeDeck Start free trial

Codex Direct Control · macOS and native Windows x64

Run Codex with VibeDeck Direct Control.

Use Codex 0.149.1 or newer. VibeDeck's local Setup guide checks the CLI, hooks, trust, and selected connection mode before it marks setup complete.

Connect normal codex from Setup for the shortest path. The dedicated launcher remains available only when PATH cannot be changed safely or you prefer not to change it.

Why VibeDeck Direct Control uses a shared Codex server Architecture

Installed hooks provide state and final responses. Direct Control provides model, effort, presets, and managed-session approval controls.

A plain Codex process normally owns a private in-process app-server. VibeDeck instead runs one loopback-only shared server so the deck and every connected session use the same controllable lifecycle. Sessions that are not connected continue to use Codex's native picker.

Direct Control requires the VibeDeck wrapper at process start because Codex selects the remote server then. Recommended PATH mode runs it automatically; the dedicated command is only a fallback. A Unix socket migration is deferred because it does not provide one daemon lifecycle on both supported platforms.

Installed Codex hooks can answer Allow once or Deny from the deck on macOS and Windows; session-wide Always is available for managed sessions when Codex offers that decision.

Choose a connection mode in local Setup

Start a controllable Codex session.

Connecting plain codex is recommended. The dedicated launcher stays available as a fallback, while status-only mode keeps hook reporting without Direct Control.

  1. 1

    Connect plain codex (recommended)

    Open VibeDeck's local Setup guide. It previews the exact addition before putting the VibeDeck launcher first in ~/.zshrc on macOS or the current user's Path on native Windows x64.

    The optional shim delegates to the real Codex executable and adds --remote only to interactive launches. It never modifies Codex files, configuration, or session history.

    Installation and removal each require a separate preview and confirmation. Open a new terminal after either change.

  2. 2

    Alternative: run without changing PATH

    Use this only if Setup cannot safely configure PATH or you prefer not to change it.

    Show the dedicated launcher command Fallback

    The command follows the current server automatically and does not modify your real Codex installation.

    macOS
    $HOME/.vibedeck/bin/vibedeck-codex
  3. 3

    Status only

    Installed hooks still report state and final responses. Direct model, effort, presets, and managed-session approvals remain unavailable until you connect a launcher.

    If Codex cannot report exact trust, run /hooks, review the VibeDeck bundle, then approve that exact installed bundle in local Setup.

Advanced connection options Manual control

Shell aliases and manual --remote are Advanced options. They use Codex's experimental app-server attachment surface and require you to keep the command aligned with the live server address.

Current manual command
codex --remote ws://127.0.0.1:<port>

Live status. Checking the shared server…

Verify a fresh session

Open a new terminal, start Codex with the selected mode, and send one prompt. Local Setup reports Verified after the first live session. If Direct Control is offline, hook state and final responses still work.

Going back to plain Codex Revert anytime

Switch modes without removing anything automatically. If the VibeDeck entry remains configured, local Setup offers a separate removal preview and confirmation.

The real Codex executable, its configuration, and session history are never changed. Already-running connected sessions continue until you close them; new sessions use the PATH visible to their new terminal.

Support boundary Read before relying on it

Direct Control uses Codex's experimental app-server API. VibeDeck currently requires Codex 0.149.1 or newer; a future Codex update may temporarily require a VibeDeck update.

Native Windows x64 is enabled, but this document does not claim live Windows acceptance. Server launch, PATH behavior, Defender, SmartScreen, terminal attachment, and deck controls must still be observed on a real Windows machine before release.

Back to support