Terminal

The terminal is the primary interface in Codemux. It uses xterm.js with a WebGL renderer (DOM fallback for environments without WebGL), Unicode 11 character widths, and the kitty keyboard protocol — backed by real PTY sessions managed in Rust.

Panes and Splits

Each tab contains a pane tree. Panes can be split horizontally or vertically, resized by dragging the divider, and swapped by dragging pane headers.

• Split right: Ctrl+Shift+D — creates a new pane to the right
• Close pane: Ctrl+Shift+W — removes the active pane
• Cycle panes: Ctrl+Shift+J (next) / Ctrl+Shift+K (previous)
• Resize pane: Ctrl+Alt+Arrow keys (5% per press)

Vim-style alternatives: Ctrl+L / Ctrl+H for pane cycling, Ctrl+Alt+H/L/K/J for resizing.

Tabs

Each workspace can have multiple tabs. Each tab has its own independent pane tree.

Tabs can be reordered by dragging. The last tab cannot be closed.

Preset Bar

The preset bar sits above the pane area and provides one-click agent launching:

• Pinned presets — Pin your most-used agent configurations for instant access. Fourteen builtins ship by default: Claude Code, Codex, OpenCode, Gemini, Antigravity, Copilot, Cursor Agent, Amp, Grok, Droid, Mastracode, Pi, Shell, and Chat Agent.
• Run button — Shows "Run" when a dev command is configured, or "Set Run" to configure one. Press Ctrl+Shift+G to run from anywhere.
• Settings — Gear icon opens preset management. Toggle bar visibility from the dropdown.

Custom presets support multiple commands, working directory overrides, and launch modes (new tab or split pane). When the bar has more pinned presets than fit on screen it becomes a horizontally-scrollable row — a plain vertical mouse wheel pans it.

Builtin Agent Presets

Every builtin agent preset launches in its CLI's skip-permissions / auto-approve ("YOLO") mode so the agent runs without per-action confirmation prompts. The exact flag was verified against each tool's own --help.

Antigravity ships alongside Gemini rather than replacing it — Google is transitioning Gemini CLI to Antigravity CLI, and Gemini CLI stops serving free/Pro/Ultra tiers on 2026-06-18.

Agent Launch and Prompt Handoff

When you create a workspace with a task description and an agent selected, Codemux automatically launches the agent and hands off your prompt:

How Prompts Are Delivered

• Claude Code and Codex — The prompt is embedded directly in the CLI command as a quoted argument (e.g., claude --dangerously-skip-permissions "fix the login bug")
• OpenCode and Gemini — The prompt is injected via PTY input after a 2-second delay, since these agents use TUI interfaces that need time to initialize

Agent Context (--system-prompt)

For Claude Code, Codemux appends --system-prompt "$CODEMUX_AGENT_CONTEXT" to the launch command. This environment variable contains instructions telling Claude Code to use Codemux's built-in browser commands instead of system browsers, and lists the available codemux browser subcommands.

The CODEMUX_AGENT_CONTEXT env var is set on all terminal sessions, so the $CODEMUX_AGENT_CONTEXT reference in the flag expands at shell execution time.

Autonomous Mode

The default Claude Code preset uses --dangerously-skip-permissions to run in autonomous mode. This skips Claude Code's interactive permission prompts, which is appropriate for agent work in Codemux where you monitor progress through the agent status indicators instead.

Custom Agent Presets

You can edit the built-in presets or create your own in Settings > Presets. When editing a Claude Code preset, keep the --system-prompt "$CODEMUX_AGENT_CONTEXT" flag for best results — this ensures the agent knows how to use Codemux's browser and tools.

Smart Headers

Terminal pane headers display contextual information:

• Agent name — When running a recognized agent (Claude, Codex, OpenCode, Gemini, Antigravity, Copilot, Cursor Agent, Amp, Grok, Droid, Mastracode, Pi), the header shows the agent name instead of the shell path
• CWD — When running a plain shell, the header shows the current working directory

Renderer

Codemux uses the xterm.js WebGL renderer by default with a DOM fallback for environments where WebGL is unavailable. Unicode 11 character widths are enabled so wide characters and emoji render at the right cell width — important for TUIs like lazygit and btop.

Pane Persistence Across Workspace Switches

Workspace switching used to dispose terminal panes — that broke alt-screen TUIs like Claude Code's "Simmering…", lazygit, vim, and btop, because the terminal's internal state (mode flags, cursor position, cell grid) would desync from the PTY producer while the pane was gone.

Codemux now keeps the xterm.js Terminal instance, its addons, the persistent wrapper element, and the PTY-output channel alive across workspace switches. On unmount the wrapper is reparented to a hidden parking node; on remount it returns to its layout container. The bytes flowing from a long-running TUI keep being processed even while the pane is off-screen, so the rendering stays in sync when you come back.

Disposal still happens on the real lifecycle events: close-pane, close-tab, close-workspace, and PTY exit all dispose the cached terminal.

Hidden-Pane Pause

If a pane is off-screen for an extended period (you've been working in another workspace), Codemux pauses its render path to remove cross-workspace typing lag. Bytes still flow into the xterm buffer; only the per-frame render is skipped while the pane has no DOM presence. Switching back un-pauses transparently.

Terminal Features

• Kitty keyboard protocol — Enhanced key reporting for tools like OpenCode
• Ctrl+Backspace — Backward kill word (sends Ctrl+W to PTY)
• Ctrl+Shift+C / Ctrl+Shift+V — Copy/paste
• Auto-resize — PTY dimensions sync when panes resize
• Status overlay — Shows terminal state (starting, ready, exited with code)

Theming

Terminal colors sync with the system theme (Omarchy integration). The 16 ANSI colors, foreground, cursor, and selection colors are all theme-reactive. When no Omarchy theme is detected, a Tokyonight-inspired fallback is used.

Persistence

Pane layout and tab structure persist across restarts. Terminal scrollback is saved on close and restored on reopen, and supported agents like Claude Code automatically resume their sessions. See Session Persistence for details on the adapter system and configuration.