Skip to content
/
Tier B A12 UI passthrough

cmux (manaflow)

cmux-manaflow · manaflow-ai/cmux · ★ 20k · last commit 2026-05-26

Primitive shape 5 total
Commands 5
00

Summary

cmux (manaflow) — Summary

cmux by manaflow-ai is a native macOS terminal application built on Ghostty (using libghostty for GPU-accelerated rendering) that adds agent-awareness on top of a standard terminal experience. It provides vertical and horizontal tab management with a sidebar showing git branch, linked PR status, working directory, listening ports, and latest notification per workspace; a notification system that picks up terminal sequences (OSC 9/99/777) and lights up panes with a blue ring when agents need attention; an in-app scriptable browser (ported from Vercel's agent-browser); SSH workspace support; and a cmux claude-teams command that runs Claude Code's teammate mode with native splits. It is distributed as a macOS DMG/Homebrew Cask (Swift/AppKit, not Electron), auto-updates via Sparkle, and reads existing ~/.config/ghostty/config. The project has 19,779 stars and 30 contributors — by far the most popular framework in this batch. Compared to the seeds, cmux is closest to a "primitive toolbox" philosophy explicitly articulated in its docs ("cmux is not prescriptive about how developers hold their tools"), making it analogous to the "Archetype 4 — Markdown scaffold, zero primitives" seeds in spirit but with a rich native GUI rather than static markdown files.

01

Overview

cmux (manaflow) — Overview

Origin

Built by manaflow-ai. 30 contributors. 19,779 GitHub stars. Active development, pushed 2026-05-26. Swift/AppKit native macOS app built on libghostty (Ghostty's rendering engine).

Philosophy — The Zen of cmux

"cmux is not prescriptive about how developers hold their tools. It's a terminal and browser with a CLI, and the rest is up to you."

"cmux is a primitive, not a solution. It gives you a terminal, a browser, notifications, workspaces, splits, tabs, and a CLI to control all of it. cmux doesn't force you into an opinionated way to use coding agents. What you build with the primitives is yours."

"The best developers have always built their own tools. Nobody has figured out the best way to work with agents yet, and the teams building closed products definitely haven't either. The developers closest to their own codebases will figure it out first."

"Give a million developers composable primitives and they'll collectively find the most efficient workflows faster than any product team could design top-down."

Why cmux Was Built

The author ran many Claude Code and Codex sessions in parallel in Ghostty with split panes. The problem: Claude Code's notification body is always just "Claude is waiting for your input" with no context, and with enough tabs open you can't read the titles. Most coding orchestrators were Electron/Tauri apps with performance issues. cmux is the answer: native Swift/AppKit, GPU-accelerated rendering via libghostty, with agent-specific notification routing on top.

Multi-Language Localization

README translated into 21+ languages, indicating broad international adoption.

02

Architecture

cmux (manaflow) — Architecture

Distribution

  • DMG: https://github.com/manaflow-ai/cmux/releases/latest/download/cmux-macos.dmg
  • Homebrew Cask: brew tap manaflow-ai/cmux && brew install --cask cmux
  • Auto-updates via Sparkle (download once, updates automatically)

Platform

  • macOS only (native Swift/AppKit)
  • GPU-accelerated terminal rendering via libghostty
  • Reads existing ~/.config/ghostty/config for themes, fonts, colors

Key Architecture Decisions

  • Not Electron/Tauri — Swift/AppKit for performance
  • libghostty — uses Ghostty's rendering engine directly (as a git submodule)
  • Socket API — scriptable via Unix socket, not just CLI flags
  • Browser porting from Vercel agent-browser — accessibility tree snapshots, element refs

Directory Structure

Native/          — Swift/AppKit app source
CLI/             — Swift CLI extensions
  CMUXCLI+AgentHookDefinitions.swift
  CMUXCLI+AmpExtension.swift
  CMUXCLI+HermesAgentHooks.swift
  CMUXCLI+Memory.swift
  CMUXCLI+TmuxCompatSupport.swift
  cmux.swift
  cmux_open.swift
Packages/        — Swift package dependencies
Prototypes/      — Experimental features
.claude/commands/ — Claude Code slash commands (pull, release, sync-branch, etc.)
.gitmodules      — ghostty, homebrew-cmux, vendor/bonsplit submodules
scripts/         — Build (setup.sh, reload.sh, cmux-debug-cli.sh)
Examples/        — Configuration examples

Required Runtime

  • macOS (version not specified in README, but likely macOS 12+)
  • No npm/node/Python required by end users
  • Ghostty compatible (reads existing config)

Config Files

  • ~/.config/ghostty/config — terminal theme/font/colors (read-only)
  • cmux.json (project-level) — custom commands per project

Target AI Tools

Claude Code (primary), OpenCode, Codex, any terminal-based agent

03

Components

cmux (manaflow) — Components

Application Features

Component Description
Sidebar Vertical tabs showing git branch, linked PR status/number, working directory, listening ports, latest notification text
Notification rings Blue ring + tab highlight when agent needs attention (picks up OSC 9/99/777 sequences)
Notification panel All pending notifications in one place, jump to most recent unread (Cmd+Shift+U)
In-app browser Scriptable browser ported from Vercel agent-browser (accessibility tree, element refs, click/fill/JS eval)
Split panes Horizontal + vertical splits
SSH workspaces cmux ssh user@remote — browser panes route through remote network
Claude Code Teams cmux claude-teams — runs teammate mode with native splits, no tmux required
Browser import Import cookies/history/sessions from Chrome, Firefox, Arc, 20+ browsers
Custom commands Project-specific actions in cmux.json launched from command palette
Theme compatibility Reads ~/.config/ghostty/config for themes

CLI Commands

Command Description
cmux ssh user@remote Create SSH workspace
cmux claude-teams Run Claude Code teammate mode with native splits
cmux notify Send notification (for agent hooks)
cmux list-workspaces List workspaces (via socket API)
cmux send Send keystrokes to workspace/surface

Claude Code Slash Commands (.claude/commands/)

Command Purpose
pull.md Pull latest main + update all submodules
release.md Release workflow
release-local.md Local release
release-nightly.md Nightly release
sync-branch.md Sync branch with main

Scriptable API

  • CLI interface for creating workspaces, splits, sending keystrokes, opening URLs
  • Unix socket API (same operations via socket)
  • CMUX_TAG environment for dogfood-tagged debug builds

Agent Hook Integration

From CLI/CMUXCLI+AgentHookDefinitions.swift and CLI/CMUXCLI+HermesAgentHooks.swift — cmux can register as a hook receiver for Claude Code and Hermes agent lifecycle events (definition in Swift CLI extension).

05

Prompts

cmux (manaflow) — Prompts

cmux is a terminal application, not a prompt framework. It ships 5 Claude Code slash commands for its own development workflow.

Excerpt 1: .claude/commands/pull.md — Submodule Update Command

# Pull

Pull latest main and update all submodules to their latest remote main. No commits, no pushes.

## Steps

1. `git pull origin main`
2. For each submodule (ghostty, homebrew-cmux, vendor/bonsplit):
   - `cd <submodule>`
   - `git fetch origin`
   - Check if behind: `git rev-list HEAD..origin/main --count`
   - If behind, merge: `git merge origin/main --no-edit`
   - Do NOT push. We only land submodule changes via PRs.
   - Go back to repo root
3. `git submodule update --init --recursive`
4. Report: current commit, which submodules were updated and by how many commits

Prompting technique: Procedural step list — explicit numbered steps with conditionals. Includes an explicit constraint ("Do NOT push") and a reporting requirement. Classic command-style prompt.

Excerpt 2: CLAUDE.md — Agent Development Notes

## Local dev

After making code changes, always run the reload script with a tag to build the Debug app:

./scripts/reload.sh --tag fix-zsh-autosuggestions

By default, reload.sh builds but does NOT launch the app... 
After a successful build, it always terminates any running app with the same tag...

Never use bare xcodebuild or open an untagged cmux DEV.app. Untagged builds share 
the default debug socket and bundle ID with other agents, causing conflicts and stealing focus.

Prompting technique: Iron-law constraints — explicit prohibitions ("Never", "Do NOT") with rationale. Common in agent-centric developer docs.

Excerpt 3: CLAUDE.md — Browser Automation Instructions

## Browser Automation

Use agent-browser for web automation. Run agent-browser --help for all commands.

Core workflow:
1. agent-browser open <url> - Navigate to page
2. agent-browser snapshot -i - Get interactive elements with refs (@e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" - Interact using refs
4. Re-snapshot after page changes

Prompting technique: Tool-use recipe — step-by-step guide for a specific tool with concrete command examples. Ref-based element addressing (@e1, @e2) is the agent-browser interaction model.

09

Uniqueness

cmux (manaflow) — Uniqueness

differs_from_seeds

cmux (manaflow) has no meaningful parallel in the 11 seeds. The seeds are all prompt frameworks, skill packs, MCP servers, or methodology documents — things that change what an AI agent does. cmux changes the environment the developer uses to watch and control agents but does not modify agent behavior. In that sense it is analogous to agent-os (Archetype 4: "markdown scaffold, zero primitives") in philosophy — both are lightweight infrastructure rather than opinionated workflow frameworks — but agent-os changes the agent's context file while cmux changes the developer's terminal experience. The closest architectural relationship is to IM.codes (also in this batch): both provide remote visibility into running agent sessions, but cmux is a local desktop app while IM.codes is a mobile/web remote-control system.

Positioning

cmux is the only native Swift/AppKit macOS terminal app in the entire corpus designed specifically for AI agent workflows. It occupies the "terminal multiplexer enhanced for agents" niche — competing conceptually with tmux+notification-scripts but implemented as a first-class native app. At 19,779 stars it is the most starred framework in this batch by a 13x margin.

Observable Failure Modes

  1. macOS-only: no cross-platform support
  2. Ghostty dependency: libghostty is a git submodule — Ghostty breaking changes could impact cmux
  3. No agent framework primitives: developers who want workflow automation must build their own on top of the primitives
  4. Single notification source: depends on agents actually emitting OSC 9/99/777 sequences or hook registrations
  5. Rapid development: large PR velocity; configuration and API may change between releases

What Is Genuinely Novel

  • GPU-accelerated terminal specifically designed for parallel AI agent monitoring
  • Sidebar with per-workspace agent-status metadata (branch + PR + ports + notification) in one view
  • cmux claude-teams as a first-class command (no tmux required for teammate mode)
  • Browser pane with SSH-aware localhost proxying alongside terminal
  • "Composable primitives" philosophy explicitly articulated as a design manifesto
04

Workflow

cmux (manaflow) — Workflow

Basic Agent Workflow

  1. Install cmux (DMG or Homebrew)
  2. Open cmux — reads ~/.config/ghostty/config for settings
  3. Start agent sessions in terminal panes (claude, codex, etc.)
  4. Sidebar shows per-workspace: git branch, PR status, working dir, ports, latest notification
  5. When agent needs input: blue ring appears on pane, tab lights up in sidebar
  6. Jump to most recent unread: Cmd+Shift+U
  7. Optionally: open browser pane alongside terminal (Cmd+Shift+L)

Multi-Agent Parallel Workflow

[workspace 1: claude, auth bug] [workspace 2: codex, performance] [workspace 3: gemini, tests]
     sidebar: branch + PR status    sidebar: branch + PR status        sidebar: branch + PR status
     🔵 waiting                      running...                          ✓ done

SSH Remote Workflow

cmux ssh user@remote
# Browser panes route through remote network
# Drag image into session → uploads via scp
# localhost URLs in browser resolve to remote machine

Claude Code Teams Workflow

cmux claude-teams
# Spawns teammates as native splits with sidebar metadata
# Each teammate has its own notification ring
# No tmux required

Custom Commands Workflow

  1. Define in cmux.json:
    {
  "commands": [{"name": "test", "command": "npm test"}]
}
  2. Open command palette → select command → runs in pane

Phase → Artifact Map

Phase Artifact
Open workspace Terminal pane + sidebar entry
Agent starts Workspace metadata in sidebar
Agent needs input OSC notification → blue ring + tab highlight
Agent completes Sidebar shows completion state

Approval Gates

None managed by cmux. User is notified (via notification ring) and decides when/whether to respond.

06

Memory Context

cmux (manaflow) — Memory & Context

Memory Architecture

cmux has no agent memory system. It is a terminal application that displays what agents output but does not store, process, or inject agent memory.

State Persistence

  • Workspace configuration (tabs, splits, SSH connections) — stored in app state, persists across launches
  • cmux.json project files — custom command definitions per project directory
  • ~/.config/ghostty/config — read-only reference for terminal appearance

No Context Injection

cmux does not inject context into agent sessions. It passes keystrokes to the terminal process; the agent receives whatever the user (or cmux send) sends.

CLI/CMUXCLI+Memory.swift

There is a CMUXCLI+Memory.swift file in the CLI directory, but its contents were not fetched. This may expose memory-related operations to agents via CLI/socket.

Cross-Session Handoff

The sidebar maintains session metadata (branch, PR status, working dir) across pane/tab switches, but this is display-only metadata, not agent context injection.

Summary

cmux's memory model is "zero" from the agent's perspective — it is transparent. The agent's own context management (compaction, handoff) is unaffected by cmux's presence.

07

Orchestration

cmux (manaflow) — Orchestration

Multi-Agent Support

Yes, but passive. cmux can host many parallel agent sessions in separate workspace panes. It does not coordinate their work — it provides the notification and sidebar infrastructure so the human can coordinate them.

Orchestration Pattern

None (from cmux's perspective). The cmux claude-teams command spawns Claude Code's built-in teammate mode, where Claude Code manages the sub-agents; cmux just provides the native splits for display.

Execution Mode

Continuous (terminal app) — runs persistently while the developer works.

Isolation Mechanism

Process isolation — each pane/workspace is a separate shell process. No git worktrees or containers managed by cmux.

Multi-Model Support

No. cmux is model-agnostic and does not route to different models. It works with any terminal-based agent.

Agent Hooks

CMUXCLI+AgentHookDefinitions.swift and CMUXCLI+HermesAgentHooks.swift define hook integrations — cmux can receive hook events from Claude Code and Hermes agents to trigger notifications. The cmux notify CLI command can be wired into agent hooks (claude code settings.json PostToolUse or Stop events) to fire notification rings.

Consensus Mechanism

None.

Prompt Chaining

No.

The cmux Philosophy on Orchestration

"cmux doesn't force you into an opinionated way to use coding agents. What you build with the primitives is yours."

Orchestration is entirely the developer's responsibility — cmux provides the visibility layer, not the coordination layer.

08

Ui Cli Surface

cmux (manaflow) — UI & CLI Surface

CLI Binary

  • Name: cmux
  • Type: Own runtime (native macOS app with CLI companion)
  • Subcommands: ssh, claude-teams, notify, list-workspaces, send (plus socket API for all operations)
  • Not a wrapper over claude/codex CLI

Desktop Application

  • Type: Native macOS terminal application (Swift/AppKit)
  • Rendering: GPU-accelerated via libghostty
  • Not Electron/Tauri — explicitly positioned as performance-first

Sidebar Features

  • Git branch per workspace
  • Linked PR status/number
  • Working directory
  • Listening ports
  • Latest notification text
  • Unread badge counts

Notification System

  • OSC 9/99/777 terminal sequence detection
  • Blue ring around pane when agent needs input
  • Tab highlight in sidebar
  • Notification panel (all pending, sorted by recency)
  • Cmd+Shift+U — jump to most recent unread

In-App Browser (split alongside terminal)

  • Scriptable API ported from Vercel agent-browser
  • Accessibility tree snapshots with interactive element refs
  • Click, fill forms, evaluate JavaScript
  • Browser import (cookies, history, sessions from Chrome/Firefox/Arc/20+ browsers)
  • SSH-aware: localhost URLs route through remote connection

Workspace Management

  • New workspace: Cmd+N
  • Workspaces 1-8: Cmd+1-8
  • Split right: Cmd+D, split down: Cmd+Shift+D
  • Directional pane focus: Option+Cmd+arrows

Observability

  • Sidebar: per-workspace live metadata (branch, PR, ports, notifications)
  • Notification panel: historical agent notification log
  • No structured logging or audit trail exposed to users

Cross-Tool Portability

High — works with any terminal-based agent (Claude Code, Codex, Gemini CLI, OpenCode, shell scripts)

Related frameworks

same archetype · same primary tool · same memory type

Goose (Block/AAIF) ★ 46k
A12 UI passthrough

General-purpose AI agent (not just code) with security-first tool inspection, recipe-based shareable configurations, and 15+ LLM…

Vibe Kanban ★ 27k
A12 UI passthrough

Eliminate the overhead of planning, switching between agent terminals, and reviewing diffs by providing a single web dashboard…

1Code ★ 5.5k
A12 UI passthrough

Cursor-like desktop experience for Claude Code and Codex with cloud background agents, event-driven automations, and a full…

Crystal (stravu) ★ 3.1k
A12 UI passthrough

Manage multiple parallel AI coding sessions in isolated git worktrees from a single desktop GUI.

Maestro (RunMaestro) ★ 3.0k
A12 UI passthrough

Orchestrate unlimited parallel AI agent sessions with a keyboard-first desktop app including Group Chat coordination and Auto Run…

AgentsMesh ★ 2.1k
A12 UI passthrough

Multi-tenant workforce platform that gives every team member a squad of AI coding agents coordinated through channels, pod…