wakemux

Why

I work in cmux with several Claude Code sessions at once. I wanted one main session that starts threads on its own, hears from them when they finish a turn and reacts.

Claude Code has this idea as a beta, called Projects. One conversation splits the work into threads and coordinates them. The threads run as cloud sessions, and you use it on claude.ai, in the desktop app or on your phone. I don't have the beta, and I want to stay in my terminal, in cmux. I found nothing that works like that there, so I built it.

What it does

wakemux runs side tasks as separate Claude Code sessions, called threads, next to the main session. Each thread gets its own Git worktree, its own branch and its own cmux workspace. I keep talking to the main session. The threads come to it.

Reports that wake the main session

When a thread ends a turn, it sends its last answer to the main session, with its branch, its commits and its uncommitted changes. cmux wakes an idle session within seconds. If cmux can't deliver, wakemux falls back to Claude Code's own messaging between sessions, then to a desktop notification.

The main session decides what it can

The main session answers what the repository rules or my earlier decisions already settle. Taste, cost, permissions, deploys and other people's PRs come to me, collected in one message. Finished threads land the way the repository wants it: as a PR or as a local merge.

No ping-pong

A thread and the main session can answer each other in circles. wakemux counts the reports on the same commit. At six, the default, the report asks the main session to stop answering and ask me. The next one becomes a desktop notification, then the reports pause until the thread commits again.

Each thread shows its state as a colored pill in the cmux sidebar: commits ahead, uncommitted changes, errors, paused reports. An optional pane lists all threads with buttons to open, hand over and clean up.

Install

Open Claude Code in a cmux terminal and paste:

Set up wakemux: clone https://github.com/mschmdb/wakemux to ~/.local/share/wakemux and follow skills/setup/SKILL.md in it.

The prompt hands the work to a setup skill in the repository. Claude checks that it runs on macOS and inside cmux, clones the repository and links it in with install.sh. Then wakemux doctor checks the machine and explains every missing piece. Claude asks before it installs software, overwrites a file or touches the shell profile.

After that it asks four questions: which GitHub organizations require PRs, which ignored files like .env each thread needs, how many threads may run per repository, and whether web projects get a browser and a dev server next to each thread. It changes only what differs from the default.

The same skill removes wakemux again. It first names threads with unmerged work and never deletes a worktree or a branch itself. install.sh --uninstall --purge puts back every file it changed.

Configuration

Every setting has a default, so wakemux runs without a config file. My own settings live in ~/.config/wakemux/config.json. Settings for one repository go into .wakemux.json in its root and get committed with it. Environment variables beat both, for example WAKEMUX_REPORT=0 for one shell session.

$ wakemux config set maxThreads 6$ wakemux config set prRequiredOrgs "acme, beta"

wakemux config set checks the value and backs up the file before the first change. wakemux config shows what applies. The full list also covers the hop limit, the branch prefix and a custom dev server command.

Status

wakemux is early, but it already works well. I have been using it for a few days, and I keep working on it, so expect changes. If you want to work on it or have a better idea for it, you are welcome. Issues and PRs go to the repository.

Open source under the MIT license, version 0.3.0. macOS, cmux and Claude Code only.