Getting Started

First session

A guided tour of the dashboard — from a blank workspace to your first Claude session, running and monitored.

purplemux is already running (if not, see Quickstart). This page walks through what the UI actually does so the first few minutes feel less abstract.

The dashboard

When you open http://localhost:8022 you land on a workspace. Think of a workspace as a folder of related tabs — one for the project you're Claude-coding, another for the docs you're writing, another for ad-hoc shell work.

The layout:

  • Left sidebar — workspaces and sessions, Claude status badges, rate-limit widget, notes, stats
  • Main area — panes inside the current workspace; each pane can have multiple tabs
  • Top bar — workspace name, split controls, settings

Toggle the sidebar any time with ⌘B. Switch Workspace/Sessions mode in the sidebar with ⌘⇧B.

Create a workspace

First run gives you one default workspace. To add another:

  1. Click + New workspace at the top of the sidebar (⌘N).
  2. Name it and pick a default directory — this is where new tabs' shells start.
  3. Hit Enter. The empty workspace opens.

You can reorder and rename workspaces later by dragging in the sidebar.

Open your first tab

A workspace starts empty. Add a tab with ⌘T or the + button on the tab bar.

Pick a template:

  • Terminal — a blank shell. Good for vim, docker, scripts.
  • Claude — starts with claude already running in the shell.
Templates are just shortcuts
Under the hood every tab is a regular shell. The Claude template is just "open a terminal and run `claude`". If you run `claude` manually in a Terminal tab later, purplemux notices and starts surfacing its status the same way.

Read the session status

Look at the sidebar session row for your tab. You'll see one of these indicators:

State Meaning
Idle (gray) Claude is waiting for your input.
Busy (purple spinner) Claude is working — reading files, running tools.
Needs input (amber) Claude hit a permission prompt or asked a question.
Review (blue) Work done, Claude stopped; there's something to check.

Transitions are near-instant. See Session status for how this is detected.

Respond to a permission prompt

When Claude asks to run a tool or edit a file, purplemux intercepts the prompt and shows it inline in the session view. You can:

  • Click 1 · Yes / 2 · Yes, always / 3 · No, or
  • Press the number keys on your keyboard, or
  • Ignore it and answer on your phone — mobile Web Push fires the same alert.

The Claude CLI never actually blocks on the intercepted prompt; purplemux pipes your answer back.

Split and switch

Once you have a tab running, try:

  • ⌘D — split the current pane to the right
  • ⌘⇧D — split downward
  • ⌘⌥←/→/↑/↓ — move focus between splits
  • ⌘⇧[ / ⌘⇧] — previous / next tab

Full list on the Keyboard shortcuts page.

Save and restore

Close the browser. Your tabs don't go anywhere — tmux holds them open on the server. Refresh in an hour (or a week) and purplemux restores the exact layout, including split ratios and working directories.

Even a server reboot is recoverable: on restart, purplemux reads the saved layout from ~/.purplemux/workspaces.json, relaunches shells in the right directories, and reattaches Claude sessions where possible.

Reach it from your phone

Run:

tailscale serve --bg 8022

On your phone, open https://<machine>.<tailnet>.ts.net, tap Share → Add to Home Screen, and grant notification permission. You now get push alerts for needs-input and review states even when the tab is closed.

Full walkthrough: PWA setup · Web Push · Tailscale.

What's next

  • Keyboard shortcuts — every binding in one table.
  • Browser support — compatibility matrix, especially iOS Safari 16.4+.
  • Explore the sidebar: Notes (⌘⇧E) for the AI daily report, Stats (⌘⇧U) for usage analytics.