Waycar with tmux · Waycar Help
Waycar with tmux
Use Waycar with tmux 3.2 or later: your tmux sessions show up as Workspaces, and you start, open, message and close agents from your phone.
Waycar works with tmux 3.2 or later as well as herdr. A tmux Host works like a herdr Host: your tmux sessions show up as Workspaces, and you can start, open, message, rename and close agents and shells from your phone.
Set up a tmux Host
Run the same install command you’d use for herdr on the machine:
curl -fsSL https://waycar.dev/install.sh | sh
It finds tmux, sets up Waycar and the Waycar hooks for live status, and offers to show a Pairing Code right in your terminal. See Install Waycar on your Host.
How tmux maps to Waycar
| tmux | Waycar |
|---|---|
| Session | Workspace |
| Window and pane | Agent or shell |
When tmux has no sessions running, tap Start Session in the Console to open one. Starting a new agent on a worktree opens it as a new tmux session, and needs git on your Host.
Opening an agent shares the window
Opening an agent shares its tmux window with your desk instead of taking it over. The window fits whichever one opened it or typed in it last. See Your desk and phone on one terminal.
A computer with herdr and tmux
On a computer with both, herdr agents and tmux sessions appear together in one list. To tell them apart, tmux cards carry a tmux badge beside their caption, and tmux entries in the Workspace menus end in “· tmux”. Hosts with only herdr or only tmux never show the mark. The Host’s page gets a Backends section:
- Show tmux sessions lists the Host’s tmux sessions. It’s on unless you turn it off. Hiding tmux sessions also stops their notifications from this Host.
- New agents start in picks herdr or tmux for New Agent on this Host. It starts on herdr unless you pick tmux.
If herdr or tmux runs into a problem, it shows its own issue with Retry while the other keeps working.
Agent status on tmux
tmux doesn’t know what an agent is doing, so Waycar gets Working, Blocked and Done from small hooks in Claude Code, Codex, omp, pi and opencode, listed in Waycar hooks for tmux. Agents without them show Unknown.
Good to know
- Everything else, including mosh, AI Usage and dictation, works the same on tmux.
- For the full list of differences, see herdr vs tmux.