claudemux

English · 简体中文

claudemux

claude + tmux. One dispatcher Claude Code session talks to you. One teammate Claude Code per repo runs in its own tmux session. You orchestrate the fleet in plain language.

Worktree default + name decoupling (1.0 cut). tm spawn <path> now takes a filesystem path; the teammate name is a flat identifier (--name, or auto <basename>-<rand4>). Every other verb takes that name. Teammates run inside a git worktree at <path>/.claude/worktrees/<name>/ by default; --no-worktree opts out. Pre-upgrade teammates must be tm kill-ed and respawned (schema 1 → 2; no silent migration). .worktreeinclude for the Codex path is a TODO — copy .env etc. into the Codex worktree by hand for now. See .agents/decisions/worktree-default-and-name-repo-decoupling.md for the why.

Architecture

flowchart TB
    user(["You<br/>(terminal · web · mobile)"])

    subgraph dispatcher_dir["dispatcher directory · the parent of your repos"]
        dispatcher["dispatcher<br/>(claude in tmux, talks to you)"]
        repoA[("repo-a/")]
        repoB[("repo-b/")]
        repoC[("repo-c/")]
    end

    subgraph teammates["teammates · one tmux session per repo"]
        tA["teammate-repo-a<br/>(claude in repo-a/)"]
        tB["teammate-repo-b<br/>(claude in repo-b/)"]
    end

    user <-->|chat| dispatcher
    user -.->|optional: direct drive<br/>via Remote Control| tA
    dispatcher -->|tm spawn / send / wait| tA
    dispatcher -->|tm spawn / send / wait| tB
    tA -.cwd.-> repoA
    tB -.cwd.-> repoB

Drive teammates from anywhere

Every teammate is a real claude REPL with a Remote Control URL. Open the URL in a browser or the mobile app and you're talking to that teammate directly — no terminal needed.

• Check on a long-running teammate from your phone on the subway.
• Hand a teammate the next task from a laptop in a cafe while the dispatcher keeps coordinating the rest of the fleet.
• Three devices, three windows, one fleet — in parallel.

Enable Remote Control in whichever scope you want:

• Per teammate (scoped). tm spawn <path> --remote-control turns it on for just that teammate; --no-remote-control keeps claudemux from enabling it (it does not suppress a user-global remoteControlAtStartup, which claude still honors — see below). Set CLAUDEMUX_REMOTE_CONTROL=1 in the dispatcher's .claude/settings.json env block to make it the default for every tm spawn. This keeps the dispatcher and any unrelated claude sessions off Remote Control — a per-spawn flag always overrides the config (precedence: explicit flag > config > off).
• Everything (global). /claudemux:setup can flip on Claude Code's user-global remoteControlAtStartup, so every claude session — dispatcher and teammates alike — registers a URL the moment it starts.

Install

In any Claude Code session:

/plugin marketplace add excitedjs/claudemux
/plugin install claudemux@claudemux
/reload-plugins

Then cd to the parent of your sibling repos and start the dispatcher:

cd ~/path/to/your/dev-dir
claude

In the REPL:

/claudemux:setup

/claudemux:setup also seeds a .workspace/ directory in your dispatcher dir holding three personalization files (persona.md, user-profile.md, principles.md) that get imported into every dispatcher session, plus notes/ and artifacts/ for long-term notes and dispatcher-generated intermediate output. The setup walks you through filling them in; you can skip and edit later. See .workspace/README.md in your dispatcher dir after setup for full layout.

Quick start

Talk in plain language — the dispatcher skill picks up the intent:

派一个 teammate 去 repo-a 跑测试

看看 repo-b 现在在干啥

让 repo-a 跑 lint,同时让 repo-b 升级 react 到 19

Or call tm directly:

tm spawn repo-a --name testbot --prompt 'run yarn test in unit-test'   # atomic: spawn + send + wait + print
tm send  testbot --prompt 'now lint'                                   # sync send: returns the reply on stdout
tm states                                                              # fleet snapshot
tm kill  testbot                                                       # done

The first positional is a <path> (here repo-a, a sibling of the dispatcher). The teammate identifier is whatever you pass via --name, or — when you omit --name — the auto-generated <basename>-<rand4> that spawn prints on stderr (spawned: repo-a-7d3a). Every other verb takes that flat identifier.

The tm script

tm is on PATH inside any Claude Code session. To use it from a regular terminal, see Outside Claude Code.