Table of Contents

Running Claude Code inside cmux

A step-by-step walkthrough for installing cmux — the native macOS terminal built for running AI coding agents in parallel — and wiring up the Claude Code CLI inside it. Screenshots are from the live cmux.com site.

macOS 14+ ~10 min free & open source cmux.com

What is cmux, exactly?

cmux is a free, open-source terminal app for Mac, built on Ghostty's rendering engine (not Electron). It's designed specifically for people running multiple AI coding agents at once — Claude Code, Codex, Gemini CLI, OpenCode, and others — instead of juggling loose terminal windows or tmux panes.

Because it's a real terminal, any agent that run s from the command line works in it out of the box. What cmux adds on top: a sidebar of vertical tabs (one per workspace/agent), a notification ring that lights up when an agent is stuck waiting on you, split panes, an in-app browser agents can drive, and a CLI/socket API for scripting it all.

❝

Vertical tabs — sidebar shows git branch, working dir, ports, and the latest notification per workspace

Notification rings — a pane glows blue when its agent needs your attention

Split panes — run Claude Code, Codex, and a browser side by side in one tab

In-app browser — agents can screenshot, click, and fill forms via a scriptable API

Session restore — reopen the app and agent sessions resume where they left off

iOS companion — your terminals sync to iPhone/iPad in realtime

PART 1 · INSTALL CMUX

1) Go to cmux.com

Open cmux.com in your browser. It's the official site — no App Store listing.

2) Click “Download for Mac”

The button in the top-right (and again in the hero) downloads the .dmg for your Mac's chip automatically. cmux supports both Apple Silicon and Intel, macOS 14.0+.

Prefer a package manager? The dropdown next to the button also offers iOS (companion app but through TestFlight) and a Nightly build. Or skip the browser entirely and use Homebrew — step 3.

3) Install it

Open the downloaded .dmg and drag cmux into your Applications folder. That's the whole install — it auto-updates itself afterward via Sparkle, so you only download once.

Or, if you'd rather use Homebrew:

brew tap manaflow-ai/cmux
brew install --cask cmux

4) Launch it

Open cmux from Applications or Spotlight (⌘ Space then type “cmux”). macOS will warn that it's from an unidentified developer — click Open to proceed.

You should land on a single workspace with a vertical tab sidebar on the left and a Ghostty-powered terminal, ready for input.

What it looks like once you're running agents — sidebar of workspaces on the left, split panes running different agents, an in-app browser, and the iOS companion mirroring a session live

PART 2 · SET UP THE CLAUDE CODE CLI

5) Open a terminal tab in cmux

Press ⌘T for a new tab, or ⌘D to split the current pane. This is just a terminal — everything below is standard shell commands, no cmux-specific syntax.

6) Install the Claude Code CLI

Use the native installer — it's the recommended path since early 2026 and needs no Node.js at all:

# one-time install, macOS/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash

# confirm it installed
claude --version
claude doctor

Prefer Homebrew or npm instead? brew install --cask claude-code works too. npm (npm install -g @anthropic-ai/claude-code) still works but now requires Node.js 22+ and is the legacy path — the native installer ships its own runtime and auto-updates in the background, so it's the one to reach for.

7) Log in and launch

You'll need a Claude Pro, Max, Team, Enterprise, or Console account — the free claude.ai plan doesn't include Claude Code access.

cd into a project directory, then run claude. On first run it opens a browser tab to authenticate — approve it, and the CLI picks up the session automatically.

cd ~/code/your-project
claude
# first run only: browser opens → approve login → back to the CLI

You're now talking to Claude Code inside a native cmux pane. Ask it to read files, run tests, open a PR — whatever you'd normally do. When it finishes a turn or needs input, the pane's tab gets a blue notification ring so you can spot it from the sidebar.

PART 3 · GET MORE OUT OF THE PAIRING

❝

cmux hooks setup

Session resume. Installs hooks so Claude Code (and Codex/OpenCode/Gemini) sessions automatically pick back up where they left off when you relaunch cmux, instead of starting fresh. For Claude specifically, also flip on Settings → Claude integration — that's what lets cmux's Claude wrapper drive the resume.

cmux claude-teams

Multi-agent teams. Launches Claude Code's teammate mode with each teammate spawned as its own native split pane, rather than a hidden background process.

⌘⇧L

In-app browser. Opens a split browser pane. Claude Code can snapshot it, click elements, fill forms, and read the page — handy for agents that need to verify a UI change themselves.

cmux notify

Manual notifications. Fire a notification from any script or hook so a pane lights up in the sidebar even outside an agent's normal flow.

❝

CLI outside cmux. To run cmux commands from a regular Terminal.app window (not just inside cmux itself), symlink the bundled binary once: sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

  1. On your Mac, open Terminal.app (Spotlight → type “Terminal”).

  2. Copy exactly this command from your post (no extra quotes or backticks):
    sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

  3. Paste it into Terminal and press Enter.

  4. macOS will prompt for your password (your Mac login password). Type it and press Enter. You won’t see characters as you type, that’s normal.

PART 4 · HAND THIS TO CLAUDE INSTEAD

If you'd rather have Claude walk you through it live — adapting to whatever error or macOS version you actually hit — copy this into any Claude chat (claude.ai, the desktop app, or Claude Code itself).

SETUP-CMUX-AND-CLAUDE-CODE.MD
Copy prompt ⬇️

I want to set up cmux (the macOS terminal app for running AI coding agents, https://cmux.com) and the Claude Code CLI on my machine, then run Claude Code inside cmux. Walk me through it step by step, one step at a time — don't dump the whole thing at once. Before each step, tell me exactly what to do and what I should see when it worked. Wait for me to confirm before moving on.

Cover, in order:

  1. Confirm my Mac meets the requirements (macOS 14+, Apple Silicon or Intel) and ask whether I want the DMG or Homebrew install.

  2. Walk me through downloading and installing cmux from cmux.com (or the brew tap/install commands), including the "unidentified developer" first-launch prompt.

  3. Help me verify cmux launched correctly (sidebar, initial workspace, terminal ready).

  4. Install the Claude Code CLI using the native installer (curl -fsSL https://claude.ai/install.sh | bash, no Node.js needed) and confirm it worked (claude --version and claude doctor). Mention Homebrew (brew install --cask claude-code) and npm (requires Node 22+, now the legacy path) as alternatives if I ask.

  5. Confirm I have a Claude Pro, Max, Team, Enterprise, or Console account — the free claude.ai plan doesn't include Claude Code — before we try to log in.

  6. Have me open a terminal tab inside cmux, cd into a real project directory, run claude, and complete the browser login step.

  7. Explain how to tell when Claude Code needs my attention inside cmux (the notification ring / sidebar tab).

  8. Briefly explain optional extras — cmux hooks setup for session resume, cmux claude-teams for multi-agent teammate panes, and the in-app browser (Cmd+Shift+L) — and ask if I want to set any of them up now.

If any command fails, diagnose the actual error I paste back rather than guessing, and give me the fix before moving to the next step.

I hope this helped you get Claude Code and cmux playing nicely together.

If you end up using this setup, I’d love to see it in the wild. Reply to this email or tag me on LinkedIn with what you’re building.

Keep building,
Jon

The First 1%

Keep Reading

View more
caret-right
© 2026 The First 1%.
beehiivPowered by beehiiv