Skip to content
/

cmux (coder) / Mux

cmux-coder · coder/cmux · ★ 1.8k · last commit 2026-05-26

Primitive shape 16 total
Commands 1 Skills 11 Subagents 2 Hooks 1 MCP tools 1
00

Summary

cmux (coder) / Mux — Summary

Mux (internally named "cmux" in the GitHub repo, branded as "Mux" by Coder Technologies) is a cross-platform Electron + React desktop application for parallel agentic development. It ships a custom agent loop (inspired by Claude Code's UX), supports multi-model routing (Claude Sonnet/Opus, GPT-5, Grok, Ollama, OpenRouter), provides isolated workspaces (local directory, git worktree, SSH remote, Coder devcontainer), and includes a rich skill/agent framework built into the .mux/ directory. The agent is named "Mux" with its own model orchestration, Plan/Exec modes, opportunistic compaction, mode prompts, and a deep-review skill that spawns parallel sub-agents. A VS Code extension and mobile server mode with responsive UI round out the surface. With 1,782 stars and 21 contributors, it is the only framework in this batch that ships both a full custom agent loop and a first-party parallel code review workflow using sub-agents. Note: despite the coder/cmux repo slug, the product is branded "Mux" and unrelated to the manaflow-ai/cmux terminal app — they share only a name coincidence.

01

Overview

cmux (coder) / Mux — Overview

Origin

Built by Coder Technologies, Inc. (coder.com). 21 contributors. 1,782 stars. AGPL-3.0 license. Active development as of 2026-05-26. Version 0.25.0 analyzed.

Philosophy

From docs/AGENTS.md:

"mux: Electron + React desktop app for parallel agent workflows; UX must be fast, responsive, predictable."

"Minor breaking changes are expected, but critical flows must allow upgrade↔downgrade without friction."

From README:

"Mux has a custom agent loop but much of the core UX is inspired by Claude Code. You'll find familiar features like Plan/Exec mode, vim inputs, /compact and new ones like opportunistic compaction and mode prompts."

Design Principles

  • Plan/Exec mode: inspired by Claude Code's Plan/Act distinction
  • Opportunistic compaction: proactively compacts context before it overflows
  • Attribution footer: all AI-generated PRs/commits must include model, thinking level, and cost metadata
  • React Compiler: auto-memoization used; manual memo/useCallback/useMemo discouraged
  • Token efficiency: "keep edits minimal and token-efficient"

PR Workflow Discipline

The .mux/skills/pull-requests/SKILL.md mandates an attribution footer on all public work:

---
_Generated with `mux` • Model: `<modelString>` • Thinking: `<thinkingLevel>` • Cost: `$<costs>`_

Product Positioning

Mux is Coder's answer to Claude Code for teams: multi-model, multi-workspace, isolated parallel development with first-party mobile access and VS Code integration. The AGPL-3.0 license signals open-source commitment but commercial backing.

02

Architecture

cmux (coder) / Mux — Architecture

Distribution

  • Pre-built binaries from GitHub Releases (macOS, Linux)
  • CLI binary: mux (dist/cli/index.js via bin.mux in package.json)
  • Package manager: bun only
  • Makefile as source of truth (not package.json scripts)

Technology Stack

  • Electron + React desktop app
  • React Compiler enabled (auto-memoization)
  • Bun package manager + runtime
  • TypeScript throughout
  • Storybook for component development
  • vitest for testing

Directory Structure

src/
  main.ts          — Electron main process
  preload.ts       — Electron preload
  App.tsx          — React root
  config.ts        — Configuration
  common/
    knownModels.ts — Authoritative model names/IDs
  cli/             — CLI binary source
  browser/         — React frontend
    features/
      ChatInput/   — Inline skill refs
      Hooks/       — Git branch details
      Messages/    — Skill snapshot rendering
.mux/              — Framework configuration dir
  agents/          — Agent definitions (plan.md, exec.md)
  skills/          — 11 skill files (SKILL.md format)
  init/            — Initialization
  tool_env         — Env vars sourced before every bash tool call
  tool_post        — Post-tool hooks
.agents/
  skills/          — Additional skills (dogfood, electron)
.claude/
  commands/        — Claude Code slash commands
  settings.json    — Hook configuration
mobile/            — Mobile React Native app
docs/              — Documentation (Mintlify)
benchmarks/        — Performance benchmarks
scripts/
  wait_pr_ready.sh
  wait_pr_checks.sh
  wait_pr_codex.sh

Config Files

  • ~/.mux/config.json — User configuration
  • ~/.mux/src/<project>/<branch> — Git worktrees
  • ~/.mux/sessions/<workspace>/chat.jsonl — Session chat history (JSONL)
  • .mux/tool_env — Sourced before every bash tool call
  • .mux.json — Project-level configuration (unknown structure)

Required Runtime

  • Node.js (Electron runtime bundled)
  • Bun (for development)
  • Git (for worktree isolation)

Target AI Tools

Built-in custom agent loop (multi-model). Claude Code is the UX inspiration but Mux runs its own loop. VS Code extension for integration. Mobile server mode.

03

Components

cmux (coder) / Mux — Components

Agent Configuration (.mux/agents/)

File Description
plan.md Plan agent — extends base plan mode; requires net LoC estimate per approach
exec.md Exec agent — execution mode agent definition

Skills (.mux/skills/ — 11 skills)

Skill Description
deep-review/SKILL.md Spawns 2-5 parallel sub-agents for code review (correctness, tests, consistency, UX, performance, docs)
pull-requests/SKILL.md PR attribution footer, lifecycle rules, CI gate workflow
tests/SKILL.md Testing guidelines
react-effects/SKILL.md React hooks patterns (anti-patterns for useEffect)
dev-desktop-sandbox/SKILL.md Desktop sandbox setup
dev-server-sandbox/SKILL.md Server sandbox setup
mobile-dev-server-sandbox/SKILL.md Mobile dev server sandbox
dogfood/SKILL.md Dogfooding instructions (eating own dog food)
electron/SKILL.md Electron-specific development patterns
generate-readme-screenshots/SKILL.md Screenshot generation automation
tbench/SKILL.md Terminal-Bench benchmark guidance

Additional Skills (.agents/skills/)

Skill Description
dogfood/SKILL.md Alternative dogfood skill
electron/SKILL.md Electron patterns

Claude Code Commands (.claude/commands/)

Command Description
commit-compact.md Commit + compact context

GitHub Prompts (.github/prompts/)

Prompt Description
auto-cleanup-fixup.md Auto cleanup/fixup actions
auto-cleanup.md Auto cleanup

Framework Features

Feature Description
Plan/Exec mode Distinct planning and execution phases
Opportunistic compaction Proactive context compaction
Mode prompts Configurable per-mode instructions
Inline skill refs @skill references in chat input
run_and_report helper Multi-step validation with clean step status
Git divergence UI Visual representation of branch divergence
Cost tracking Per-workspace token consumption + cost display
Context management dialog Compaction controls in one place

Model Support (knownModels.ts)

  • claude-sonnet-4-* (multiple variants)
  • claude-opus-4-*
  • gpt-5-*
  • grok-*
  • Ollama (local LLMs)
  • OpenRouter (long-tail LLMs)
05

Prompts

cmux (coder) / Mux — Prompts

Excerpt 1: .mux/skills/deep-review/SKILL.md — Sub-Agent Review Orchestration

---
name: deep-review
description: Sub-agent powered code reviews spanning correctness, tests, consistency, and fit
advertise: false
---

# Deep Review Mode

Provide an **excellent code review** by defaulting to **parallelism**.

You should use sub-agents to review the change from multiple angles (correctness, tests, 
consistency, UX, performance, safety). Each sub-agent should have a focused mandate and 
return actionable findings with file paths.

## Spawn the right sub-agents (change-type aware)

Spawn **2–5** sub-agents depending on scope. Tailor them to the change.

### Suggested sub-agent set
- **Correctness & edge cases** (always) — find logic bugs, missing error handling, race conditions
- **Tests & verification** (always) — evaluate coverage, propose missing tests
- **Consistency & architecture** (usually) — ensure changes match existing patterns
- **UX & accessibility** (when UI changed) — keyboard flows, a11y, empty/loading/error states
- **Performance & reliability** (when hot paths changed) — latency, blocking calls, memory growth
- **Docs & developer experience** (when public API changed) — clarity, correctness, link integrity

Prompting technique: Parallel sub-agent dispatch — explicit mandate to spawn 2-5 sub-agents with specific roles. Change-type-aware routing (UI changes get UX sub-agent, hot paths get performance sub-agent). This is the most sophisticated prompt orchestration pattern in this batch.

## Attribution Footer

Public work (issues/PRs/commits) must use 🤖 in the title and include this footer in the body:

_Generated with `mux` • Model: `<modelString>` • Thinking: `<thinkingLevel>` • Cost: `$<costs>`_

<!-- mux-attribution: model=<modelString> thinking=<thinkingLevel> costs=<costs> -->

Always check $MUX_MODEL_STRING, $MUX_THINKING_LEVEL, and $MUX_COSTS_USD via bash before 
creating or updating PRs—include them in the footer if set.

## Lifecycle Rules
- Never enable auto-merge or merge into main yourself. The user must explicitly merge PRs.
- PR readiness: (1) Codex confirms approval, (2) all Codex review threads resolved, 
  (3) all required CI checks pass. MUST NOT report success before these conditions are met.

Prompting technique: Iron-law constraints with explicit completion criteria ("MUST NOT report success before these conditions are met") and traceability metadata injection (model + cost in every PR).

Excerpt 3: .mux/agents/plan.md — Agent Mode Extension

---
name: Plan
base: plan
---

- Attach a net LoC estimate (product code only) to each recommended approach.

Prompting technique: Minimal delta extension — extends the base plan mode with a single additional requirement (LoC estimate). Demonstrates how Mux's agent configuration format works: YAML frontmatter + markdown body.

09

Uniqueness

cmux (coder) / Mux — Uniqueness

differs_from_seeds

Mux (coder/cmux) is most similar to claude-flow among the seeds: both ship custom agent loops, support multi-model routing, provide parallel workspaces, and implement code review sub-agents. The architectural delta: claude-flow is an npm CLI that augments Claude Code via MCP, whereas Mux is a full Electron desktop app with its own agent loop that does not depend on Claude Code CLI at all. Mux's deep-review skill (parallel sub-agents for code review) closely mirrors claude-flow's hive-mind consensus protocols but is simpler (gather + synthesize vs. byzantine consensus). The worktree isolation and git divergence UI have no parallel in any seed except superpowers (which uses worktrees). The attribution footer requirement (model + thinking level + cost in every PR) is a unique governance discipline not found in any seed.

Positioning

Mux is Coder's multi-model replacement for Claude Code CLI — targeting teams who need workspace isolation, cost visibility, and provider flexibility. The AGPL-3.0 license signals open-source but corporate-backed product. It competes with Claude Code Max in the high-end developer market.

Observable Failure Modes

  1. Electron app: larger bundle, higher memory than terminal-native approaches
  2. Own agent loop: not benefiting from Claude Code's battle-tested session management and tool implementations
  3. AGPL license: viral copyleft may deter commercial use in some organizations
  4. Rapid development v0.25.0: breaking changes expected, "upgrade↔downgrade without friction" is a stated but aspirational goal
  5. Codex dependency in PR workflow: requires Codex review bot to be configured in repo

What Is Genuinely Novel

  • Attribution footer requirement for all AI-generated PRs (model + thinking level + cost) — a governance primitive for AI-generated code accountability
  • Opportunistic compaction (proactive before overflow) vs reactive compaction
  • deep-review skill as a first-class sub-agent orchestration pattern for code review
  • Mux mode prompts — different system prompts for Plan vs Exec modes
  • Net LoC estimate required in Plan mode — a code-size discipline enforcement
  • Cross-platform (macOS + Linux) with mobile server mode
04

Workflow

cmux (coder) / Mux — Workflow

Agent Development Workflow

  1. Install Mux from releases
  2. Configure ~/.mux/config.json (model, API keys)
  3. Open project → creates workspace
  4. Choose runtime: Local / Worktree / SSH / Coder devcontainer
  5. Enter Plan mode → agent proposes plan with net LoC estimates
  6. Review mermaid diagram of proposed changes
  7. Enter Exec mode → agent executes
  8. Opportunistic compaction fires if context approaches threshold
  9. Git divergence UI shows branch state across workspaces
  10. Deep-review skill spawns parallel sub-agents for code review

PR Workflow (from .mux/skills/pull-requests/SKILL.md)

  1. Branch name reflects the work; base is main
  2. Local validation: make static-check
  3. Push branch
  4. ./scripts/wait_pr_ready.sh <pr_number> — polls Codex + CI together
  5. Address Codex review comments
  6. Re-request review: @codex review on PR
  7. PR is ready when: Codex thumbs-up + all threads resolved + all CI checks pass
  8. User must explicitly merge — agent never merges

Phase → Artifact Map

Phase Artifact
Plan mode Proposed plan with mermaid diagram
Exec mode Code changes + git diff
PR creation PR with attribution footer (model, thinking level, cost)
Deep review Consolidated review from 2-5 parallel sub-agents
Session ~/.mux/sessions/<workspace>/chat.jsonl

Approval Gates

Gate Type Description
Plan review file-review Human reviews proposed plan before exec
PR merge typed-confirm User must explicitly approve merge (never auto-merged)
Codex review freetext-clarify Codex review gate before PR readiness
CI checks yes-no All required CI checks must pass
06

Memory Context

cmux (coder) / Mux — Memory & Context

Session Storage

  • ~/.mux/sessions/<workspace>/chat.jsonl — Per-workspace chat history in JSONL format
  • JSONL format enables append-only writes and streaming reads without full-file parsing

Workspace State

  • ~/.mux/config.json — Global configuration (models, API keys, settings)
  • ~/.mux/src/<project>/<branch> — Git worktree paths per project/branch
  • State persists across Mux restarts

Compaction

Mux implements two compaction modes:

  1. /compact — Manual compaction (same as Claude Code)
  2. Opportunistic compaction — Proactively fires when context approaches the threshold, before overflow. This is novel vs Claude Code's reactive compaction.

Context management dialog in UI provides unified compaction controls.

Context Injection

  • .mux/tool_env is sourced before every bash tool call — injects environment variables (including MUX_MODEL_STRING, MUX_THINKING_LEVEL, MUX_COSTS_USD)
  • .mux/tool_post — post-tool hook execution
  • Mode prompts — configurable per-mode context (Plan mode vs Exec mode have different prompts)

Cross-Session Handoff

Chat history in JSONL is persistent. Session can be resumed. No explicit handoff spec found.

Memory Type

File-based (JSONL). No vector DB or graph DB. No cross-workspace memory sharing.

Inline Skill References

src/browser/features/ChatInput/utils.inlineSkillRefs.test.ts — Skills can be referenced inline in chat messages (@skill-name), injecting the skill's content as context. This is a form of on-demand context injection.

07

Orchestration

cmux (coder) / Mux — Orchestration

Multi-Agent Support

Yes. Mux explicitly supports parallel workspaces with multiple agents running simultaneously. The deep-review skill orchestrates 2-5 parallel sub-agents for code review.

Orchestration Pattern

Parallel-fan-out for the deep-review skill: one orchestrator spawns 2-5 sub-agents with different mandates (correctness, tests, consistency, UX, performance, docs), then synthesizes their findings into a consolidated review.

Hierarchical for workspace management: one Mux instance manages multiple workspaces, each with independent agent context.

Execution Mode

Interactive-loop with opportunistic compaction. The agent runs within Mux's custom loop (not the Claude Code CLI loop directly). Plan/Exec mode transitions are user-controlled.

Isolation Mechanism

Multiple isolation options:

  • Local: edits in-place in project directory
  • Worktree: git worktrees at ~/.mux/src/<project>/<branch> — one per feature branch
  • SSH: remote execution on server over SSH
  • Coder devcontainer: container-based isolation via Coder platform

Worktree isolation is the recommended approach for parallel development.

Multi-Model Support

Yes. Explicit model routing per workspace from src/common/knownModels.ts:

  • claude-sonnet-4-* (multiple variants)
  • claude-opus-4-*
  • gpt-5-*
  • grok-*
  • Ollama (local models)
  • OpenRouter (long-tail)

Different workspaces can use different models. No fixed role-to-model mapping in config — user chooses per workspace.

Consensus Mechanism

None. Deep review is a parallel gather + human-synthesized review, not a formal consensus protocol.

Prompt Chaining

Yes. .mux/tool_post enables post-tool prompt chaining. The deep-review skill implicitly chains: sub-agent results → synthesis prompt → final review.

Custom Agent Loop

Mux runs its own agent loop (not just a wrapper around Claude Code CLI). Features not in Claude Code: opportunistic compaction, mode prompts, worktree-per-feature, cost tracking per workspace.

08

Ui Cli Surface

cmux (coder) / Mux — UI & CLI Surface

CLI Binary

  • Name: mux (from bin.mux in package.json, dist/cli/index.js)
  • Type: Own runtime (custom agent loop, not a wrapper over claude/codex)
  • Subcommands: unknown (CLI source not fully read)

Desktop Application

  • Type: Electron + React desktop app
  • Platforms: macOS, Linux (pre-built binaries)
  • UI features:
    • Projects sidebar (left panel)
    • Workspace management with runtime selector (Local/Worktree/SSH/Coder)
    • Plan mode with mermaid diagram rendering
    • Exec mode
    • Git divergence view across workspaces
    • Integrated code review panel
    • Cost tracking per workspace
    • Context management dialog (compaction controls)
    • Vim keybindings
    • LaTeX rendering
    • @skill inline skill references in chat

Mobile Server Mode

Mux has a "server mode" with a responsive UI for mobile users. Screenshots show mobile layout. This appears to be a web server accessible from a mobile browser (not a native mobile app).

VS Code Extension

First-party VS Code extension: "Jump into Mux workspaces directly from VS Code." Allows navigating to Mux workspaces from within VS Code.

Storybook

Component development via Storybook (.storybook/ directory). make test:storybook in CI.

Observability

  • Cost tracking per workspace (token usage + USD cost, displayed in UI)
  • MUX_MODEL_STRING, MUX_THINKING_LEVEL, MUX_COSTS_USD env vars in tool_env
  • Attribution footer on all PRs: model + thinking level + cost
  • Git divergence UI across workspaces

Cross-Tool Portability

Low-medium — Mux is its own agent runtime. It does not run inside Claude Code CLI or other agents; it replaces them with its own loop. VS Code extension provides integration without replacing the agent loop.

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…