# cmux — Plain-Language Wiki

> cmux is a macOS terminal app built on the Ghostty terminal engine, designed specifically for running AI coding agents. It adds vertical tabs, notification rings, split panes, an in-app browser, and a socket-based CLI so agents can control the UI programmatically.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a)
- [GitHub repository](https://github.com/manaflow-ai/cmux)

## Repository

- Repository: manaflow-ai/cmux

- Generated: 2026-05-24T05:25:51.692Z
- Updated: 2026-05-24T05:29:15.806Z
- Runtime: Claude Code
- Format: Explain Like I'm 5
- Pages: 6

## Pages

- [Explain It Simply](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/01-explain-it-simply.md): What 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.
- [Five Ideas to Keep in Your Head](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/02-five-ideas-to-keep-in-your-head.md): The 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.
- [Workspaces, Surfaces & Panels — How the Screen Is Organized](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/03-workspaces-surfaces-panels-how-the-screen-is-organized.md): A 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.
- [Notification Rings — How Agents Get Your Attention](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/04-notification-rings-how-agents-get-your-attention.md): When 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.
- [The Socket & CLI — How Agents Drive cmux Programmatically](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/05-the-socket-cli-how-agents-drive-cmux-programmatically.md): The 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.
- [The One Analogy to Keep & What to Read Next](https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/pages/06-the-one-analogy-to-keep-what-to-read-next.md): A 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.

## Source Files

- `CLAUDE.md`
- `CLI/CLISocketPathResolver.swift`
- `CLI/cmux.swift`
- `CLI/CMUXCLI+Events.swift`
- `daemon/remote/go.mod`
- `ghostty.h`
- `Packages/CMUXAgentLaunch`
- `README.md`
- `skills.sh`
- `Sources/AppDelegate.swift`
- `Sources/cmuxApp.swift`
- `Sources/CmuxConfig.swift`
- `Sources/ContentView.swift`
- `Sources/GhosttyTerminalView.swift`
- `Sources/NotificationsPage.swift`
- `Sources/Panels/BrowserPanel.swift`
- `Sources/Panels/Panel.swift`
- `Sources/Panels/TerminalPanel.swift`
- `Sources/SocketControlSettings.swift`
- `Sources/TabManager.swift`
- `Sources/TerminalNotificationCallerResolver.swift`
- `Sources/TerminalNotificationPolicy.swift`
- `Sources/TerminalNotificationQueue.swift`
- `Sources/TerminalNotificationStore.swift`
- `Sources/Workspace.swift`
- `Sources/WorkspaceContentView.swift`