CLUI — Command Line User Interface for Codex

A lightweight, transparent desktop overlay for Codex on macOS. CLUI wraps the Codex CLI/app-server in a floating pill interface with multi-tab sessions, a permission approval UI, voice input, and a skills marketplace.

Features

• Floating overlay — transparent, click-through window that stays on top. Toggle with ⌥ + Space (fallback: Cmd+Shift+K).
• Multi-tab sessions — each tab opens its own Codex session with independent session state.
• Permission approval UI — intercepts tool calls via PreToolUse HTTP hooks so you can review and approve/deny from the UI.
• Conversation history — browse and resume past Codex threads.
• Skills marketplace — browse Codex-native skills, plugins, and apps without leaving CLUI.
• Voice input — local speech-to-text via Whisper (required, installed automatically).
• File & screenshot attachments — paste images or attach files directly.
• Dual theme — dark/light mode with system-follow option.

Why CLUI

• Codex, but visual — keep CLI power while getting a fast desktop UX for approvals, history, and multitasking.
• Human-in-the-loop safety — tool calls are reviewed and approved in-app before execution.
• Thread-native workflow — each tab runs an independent Codex thread you can resume later.
• Local-first — everything runs through your local Codex CLI. No telemetry, no cloud dependency.

How It Works

UI prompt → Main process routes to Codex app-server → event stream → live render
                                         → tool call? → permission UI → approve/deny

See docs/ARCHITECTURE.md for the full deep-dive.

Install App (Recommended)

The fastest way to get CLUI running as a regular Mac app. This installs dependencies, voice support (Whisper), builds the app, copies it to /Applications, and launches it.

1) Clone the repo

git clone https://github.com/justjxke/clui.git

2) Double-click install-app.command

Open the clui folder in Finder and double-click install-app.command.

First launch: macOS may block the app because it's unsigned. Go to System Settings → Privacy & Security → Open Anyway. You only need to do this once. Folder cleanup: the installer removes temporary dist/ and release/ folders after a successful install to keep the repo tidy.

After the initial install, just open CLUI from your Applications folder or Spotlight.

Terminal / Developer Commands

Only install-app.command is kept at root intentionally for non-technical users. Developer scripts live in commands/.

Quick Start (Terminal)

git clone https://github.com/justjxke/clui.git

cd clui

./commands/setup.command

./commands/start.command

Press ⌥ + Space to show/hide the overlay. If your macOS input source claims that combo, use Cmd+Shift+K, or set a custom keybind in the ... menu.

To stop:

./commands/stop.command

Developer Workflow

npm install

npm run dev

Renderer changes update instantly. Main-process changes require restarting npm run dev.

Other Commands

Command	Purpose
./commands/setup.command	Environment check + install dependencies
./commands/start.command	Build and launch from source
./commands/stop.command	Stop all CLUI processes
npm run build	Production build (no packaging)
npm run dist	Package as macOS .app into release/
npm run doctor	Run environment diagnostic

Setup Prerequisites (Detailed)

You need macOS 13+. Then install these one at a time — copy each command and paste it into Terminal.

Step 1. Install Xcode Command Line Tools (needed to compile native modules):

xcode-select --install

Step 2. Install Node.js (recommended: current LTS such as 20 or 22; minimum supported: 18). Download from nodejs.org, or use Homebrew:

brew install node

Verify it's on your PATH:

node --version

Step 3. Make sure Python has setuptools (needed by the native module compiler). On Python 3.12+ this is missing by default:

python3 -m pip install --upgrade pip setuptools

Step 4. Install Codex:

npm install -g @openai/codex

Step 5. Authenticate Codex (follow the prompts that appear):

codex

Step 6. Install Whisper for voice input:

# Apple Silicon (M1/M2/M3/M4) — preferred:
brew install whisperkit-cli
# Apple Silicon fallback, or Intel Mac:
brew install whisper-cpp

No API keys or .env file required. CLUI uses your existing Codex authentication.

Architecture and Internals

Project Structure

src/
├── main/                   # Electron main process
│   ├── codex/              # ControlPlane, app-server client, EventNormalizer
│   ├── hooks/              # PermissionServer (PreToolUse HTTP hooks)
│   ├── marketplace/        # Plugin catalog fetching + install
│   ├── skills/             # Skill auto-installer
│   └── index.ts            # Window creation, IPC handlers, tray
├── renderer/               # React frontend
│   ├── components/         # TabStrip, ConversationView, InputBar, etc.
│   ├── stores/             # Zustand session store
│   ├── hooks/              # Event listeners, health reconciliation
│   └── theme.ts            # Dual palette + CSS custom properties
├── preload/                # Secure IPC bridge (window.clui API)
└── shared/                 # Canonical types, IPC channel definitions

How It Works

1. Each tab opens a Codex session through the local app-server.
2. Event messages are parsed by CodexAppServerClient and normalized by CodexEventNormalizer.
3. ControlPlane manages tab lifecycle (connecting → idle → running → completed/failed/dead).
4. Tool permission requests arrive via HTTP hooks to PermissionServer (localhost only).
5. The renderer polls backend health every 1.5s and reconciles tab state.
6. Sessions are resumed with --resume <session-id> for continuity.

Network Behavior

CLUI operates almost entirely offline. The only outbound network calls are:

Endpoint	Purpose	Required
raw.githubusercontent.com/anthropics/*	Marketplace catalog (cached 5 min)	No — graceful fallback
api.github.com/repos/anthropics/*/tarball/*	Skill auto-install on startup	No — skipped on failure

No telemetry, analytics, or auto-update mechanisms. All core Codex interaction goes through the local CLI.

Troubleshooting

For setup issues and recovery commands, see docs/TROUBLESHOOTING.md.

Quick self-check:

npm run doctor

Tested On

Component	Version
macOS	15.x (Sequoia)
Node.js	20.x LTS, 22.x
Python	3.12 (with setuptools installed)
Electron	33.x

Known Limitations

• macOS only — transparent overlay, tray icon, and node-pty are macOS-specific. Windows/Linux support is not currently implemented.
• Requires Codex — CLUI is a UI layer, not a standalone AI client. You need an authenticated codex installation.
• Permission mode — uses --permission-mode default. The PTY interactive transport is legacy and disabled by default.

License

MIT