cmux — Plain-Language Wiki

Pages

1. Explain It SimplyWhat cmux does in plain language: a Ghostty-powered macOS terminal that treats AI coding agents as first-class citizens, with vertical tabs, notification rings, an in-app browser, and a CLI that lets agents drive the UI over a Unix socket.
2. Five Ideas to Keep in Your HeadThe handful of concepts — workspace, surface, socket, notification, panel — that unlock every other part of the codebase. Understanding these five terms means understanding how cmux hangs together.
3. Workspaces, Surfaces & Panels — How the Screen Is OrganizedA workspace is one tab (row in the sidebar). Each workspace can be split into multiple surfaces (terminal panes). Panels are extra panes — browser, file preview, markdown viewer — that live alongside terminals. This page traces how TabManager creates, tracks, and switches between them.
4. Notification Rings — How Agents Get Your AttentionWhen an AI coding agent needs input, cmux lights up a blue ring around the pane and badges the sidebar tab. This page explains the queue, policy, and store that decide when to ring, how rings are cleared, and why the removal calls run off the main thread to avoid UI freezes.
5. The Socket & CLI — How Agents Drive cmux ProgrammaticallyThe cmux CLI connects to a Unix socket that the running app exposes. Agents (Claude Code, Codex, etc.) send commands over that socket to create workspaces, send keystrokes, report metadata to the sidebar, and trigger notifications — all without touching the GUI. This page covers the CLI entry point, the socket path rules, and the Go-based remote daemon used for SSH sessions.
6. The One Analogy to Keep & What to Read NextA short plain-English recap: cmux is a terminal window manager where every tab is a workspace, every split is a surface, the sidebar is a live dashboard, and the socket is the intercom agents use to talk to the app. What to look at next depending on whether you are building an agent integration, customizing the UI, or hacking on the terminal core.