# 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:

```sh
curl -fsSL https://waycar.dev/install.sh | sh
```

It finds tmux, sets up Waycar and the [Waycar hooks](https://waycar.dev/help/tmux-hooks) for live status, and offers to show a Pairing Code right in your terminal. See [Install Waycar on your Host](https://waycar.dev/help/install).

## 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](https://waycar.dev/help/worktrees) 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](https://waycar.dev/help/take-over).

## 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. Agents without them show Unknown. See [Waycar hooks for tmux](https://waycar.dev/help/tmux-hooks).

## Good to know

- Everything else, including [mosh](https://waycar.dev/help/mosh), AI Usage and dictation, works the same on tmux.
- For the full list of differences, see [herdr vs tmux](https://waycar.dev/help/herdr-vs-tmux).

---

Waycar Help › Hosts and connections: https://waycar.dev/help/tmux