CLI

The codemux command lets you control a running Codemux instance from any terminal. It can also boot the full backend without a desktop window for Web Remote Access. Agents use the CLI to interact with the browser, manage project memory, and send notifications programmatically.

How It Connects

The CLI communicates with Codemux over a local IPC channel.

On Linux and macOS this is a Unix socket:

• $XDG_RUNTIME_DIR/codemux.sock (standard path)
• /tmp/codemux-{uid}/codemux.sock (fallback when XDG_RUNTIME_DIR is unset)

On Windows it is a named pipe instead — \\.\pipe\codemux-{username}. There is no socket file to inspect.

Control commands send a JSON request to the socket and receive a JSON response. If Codemux isn't running, they fail with a connection error. codemux serve is the exception: it starts the backend itself and owns the socket until it exits.

Commands

Browser Control

Control the embedded browser pane from the terminal. This is the primary way AI agents interact with web pages.

codemux browser open <url>              # Navigate to a URL
codemux browser snapshot                # Get accessibility tree
codemux browser snapshot --dom          # Get DOM-based element tree
codemux browser click "<selector>"      # Click element by CSS selector
codemux browser fill "<selector>" "text" # Type into an input field
codemux browser screenshot              # Capture viewport as base64 PNG
codemux browser console-logs            # Get browser console output
codemux browser viewport <preset|WxH|reset>  # Resize viewport for responsive testing
codemux browser viewport-presets        # List available viewport presets

Coordinate-based commands for iframes, shadow DOM, canvas, and protected inputs:

codemux browser click-at <x> <y>                     # Click at pixel coordinates
codemux browser type-at "text" --x <x> --y <y>       # Type at coordinates
codemux browser scroll-at <x> <y> --direction down    # Scroll at coordinates
codemux browser key-press "Enter"                     # Send keyboard event
codemux browser drag <x1> <y1> <x2> <y2>             # Drag between points

OS-level input via ydotool (stealth mode, requires headed browser + Hyprland):

codemux browser click-os <x> <y>                     # OS-level click
codemux browser type-os "text" --x <x> --y <y>       # OS-level typing

See Browser Agent Commands for full details.

Project Memory

Store and retrieve project context that persists across agent sessions.

codemux memory show                                         # Display project memory
codemux memory set --goal "Ship auth feature" --focus "OAuth flow"  # Update memory fields
codemux memory add decision "Use JWT for sessions" --tag auth       # Add a memory entry

Memory entry kinds: pinned_context, decision, next_step, session_summary.

Code Index

Build and search a code index for the current project.

codemux index build                    # Build/rebuild the search index
codemux index status                   # Show index status
codemux index search "handleAuth" --limit 20  # Search indexed code

Other Commands

codemux status                         # Check if Codemux is running
codemux notify "Build complete"        # Send a notification
codemux handoff                        # Generate a project handoff summary
codemux capabilities                   # List all commands as JSON
codemux app                            # Launch the desktop app
codemux mcp                            # Run the stdio MCP server
codemux json <command> [params]        # Raw control-socket escape hatch

codemux json sends any control command verbatim — useful for anything without a dedicated subcommand:

codemux json get_app_state
codemux json split_pane '{"pane_id":"pane-1","direction":"horizontal"}'

GitHub Issues

codemux issue list [--search <q>] [--state open|closed|all]
codemux issue view <number>
codemux issue link <number>            # Link an issue to the active workspace

Workspace Maintenance

codemux workspace rerun-setup [workspace-id]   # Re-run setup scripts

Ports

codemux ports hands out a stable, collision-free port per worktree — the thing you need when three worktrees of the same repo all want to run npm run dev at once.

codemux ports allocate web        # prints just the number, e.g. 10004
codemux ports list                # name<TAB>port, one per line
codemux ports release web

There are no flags and no environment variables. Identity comes from the worktree root (git rev-parse --show-toplevel, canonicalized), so linked worktrees of one repository are distinct — which is the whole point. Outside a repo, the current directory stands in.

• Range is 10000–32767 — above the usual dev defaults (3000, 4200, 5173, 8000, 8080) and below Linux's ephemeral range.
• A port is only handed out if it's unreserved and actually bindable on both 0.0.0.0 and 127.0.0.1.
• Determinism comes from persistence, not hashing. The (worktree → name → port) mapping is recorded, so allocate with the same name in the same worktree always reprints the same number.
• Allocations are stored under your data directory, written atomically and guarded by a lock file, so concurrent allocate calls in parallel worktrees can't collide or lose each other's writes.
• Exhaustion is explicit: "no free port in 10000-32767; free one with codemux ports release <name>".

The output contract is designed for scripts — allocate prints the bare number on stdout and everything else on stderr:

PORT=$(codemux ports allocate web) npm run dev

This is different from .codemux/ports.json, which declares ports for detection. That file describes what a project uses; codemux ports hands out a number nothing else is using.

Web Remote Access

Manage Web Remote Access for a running desktop:

codemux remote enable                              # Use the saved scope and port
codemux remote enable --scope tailscale --port 4377
codemux remote pair
codemux remote pair --name "work laptop"
codemux remote disable

On a machine with no desktop session, run the full backend headlessly instead:

codemux serve [--scope all|tailscale|loopback] [--port N] [--relay]

serve prints reachable links and a pairing QR, then stays in the foreground until Ctrl+C or SIGTERM. See Web Remote Access.

Account Sign-In And One-Command Setup

These work from a bare shell — no GUI, no display, and no running Codemux instance — so a VPS reached over SSH can be set up entirely over the wire:

codemux login                          # Prompt for email and password
codemux login --email you@example.com
codemux login --token <session-token>  # For GitHub accounts with no password
codemux login --status                 # Same output as codemux whoami
codemux logout

codemux connect is the one-command path: it signs in if needed, turns on from-anywhere (relay) access, and installs a background service so the machine stays reachable after you log out.

codemux connect
codemux connect --email you@example.com --scope tailscale --port 4377
codemux connect status                 # Account, config, service, running instance
codemux connect off                    # Alias: disconnect

It is safe to re-run — it reports the steps already done rather than undoing them. With a Codemux instance already running on the machine it drives that instance over the control socket instead of installing a service, since two backends would fight over the port and the database. connect off removes the service and turns relay mode off but leaves you signed in; use codemux logout to clear the session.

See Web Remote Access for the full flow and what the service unit does.

Monitoring

Let an agent declare that it is watching something in the background — a CI run, a tailed process, a PR poll — so its workspace shows the calm Monitoring status instead of staying pinned at "Working":

codemux monitor start
codemux monitor start --reason "watching CI for #248"
codemux monitor status
codemux monitor stop

The common call takes no arguments — it targets the agent's own pane by reading CODEMUX_PANE_ID and CODEMUX_WORKSPACE_ID from the environment Codemux injects. Pass --pane-id to target a different pane. This is provider-agnostic: it works from a terminal agent, Codex, or OpenCode, not just Claude.

Diagnostics

These run without a running Codemux instance — they read local files and probe the environment directly, so they work precisely when the app itself is misbehaving:

codemux logs [--tail <n>]              # Print recent app log lines (default 200)
codemux doctor                         # Diagnose the local environment

codemux doctor reports desktop/session info, where the log file lives, and — on Linux — whether a file-dialog backend is available. On a minimal window manager (i3, dwm, …) with no XDG desktop portal and no zenity, native file pickers can't open and actions like "Open Project" silently do nothing. The fix is to install xdg-desktop-portal plus a backend (e.g. xdg-desktop-portal-gtk), or install zenity; doctor prints a cause-specific hint and tells the difference between "portal not installed" and "portal installed but not starting."

How Agents Use It

Every terminal session in Codemux has environment variables that tell agents they're running inside Codemux:

Claude Code receives CODEMUX_AGENT_CONTEXT via --system-prompt, which instructs it to use codemux browser commands instead of launching system browsers or headless Chromium.

MCP Server

Codemux also exposes its control interface as a 57-tool MCP server (codemux mcp), providing browser, workspace, archive, git, automation, and other control tools over JSON-RPC for AI agents that support the Model Context Protocol.