Skip to content

Guides

tmux

Mucq sets up the tmux it needs by itself. Install tmux, leave your config alone, and here's what's worth knowing.

On this page

tmux is where your sessions live. It keeps Claude running on the server when you close the lid, lock the phone or lose the connection, and it lets the Mac, the iPhone and the iPad all look at the same session.

You don't need to configure it for Mucq. Install it, and don't hand-tune anything on Mucq's account.

One session per project

Each project runs in a tmux session named after its folder. ~/projects/webshop runs in webshop. A few characters, such as . and :, become _, so my.app runs in my_app.

The project's shell, ⌘T, has a session of its own beside it: webshop+shell. To attach a project to a session with another name, set tmux session in Edit Project… (⌘I).

Mucq uses your normal tmux server, the one a plain tmux command talks to. So you can see the same sessions from any terminal:

Shell
tmux ls
tmux attach -t =webshop

The = makes tmux match the name exactly, the way Mucq does.

What Mucq sets

  • No status line on the sessions it opens. Mucq shows the state itself.
  • A few options of its own on each session, named @mucq_…. They hold the settings Claude was started with and the state Claude reports. Leave them alone.
  • Focus events, for the whole tmux server, while Fit shared sessions is on in Settings › Sessions. That's what lets a shared session take the size of the device you're using.

Mucq doesn't read or write your ~/.tmux.conf, and doesn't change anything else.

What to leave alone

  • window-size. tmux's default lets a shared session follow the device you're using. A config that sets it to smallest, largest or manual keeps that size instead.
  • Session names. Renaming a project's session by hand makes Mucq start a new one next time. Use tmux session in Edit Project… instead.
  • A claude alias that adds flags. Mucq starts Claude with the permission mode from Settings › Claude Code; an alias that adds flags of its own can override it.

Scrolling and copy mode

If your tmux config has mouse on, scrolling in the terminal puts tmux into copy mode, where it shows the session's history. Press q to leave it. While a session is in copy mode, Mucq doesn't paste file paths into it; it offers Copy Path instead.

Ending a session

End Session… in Mucq ends the project's tmux session and its shell. From a terminal, this does the same for the Claude session:

Shell
tmux kill-session -t =webshop

The project stays pinned. Opening it again starts a new session and a new Claude.