## Get started

- **What is Waycar?** Waycar is a native iPhone and iPad app for checking on and talking to the coding agents you run in herdr or tmux on your own machines.
- **Requirements** What your iPhone or iPad and your Host need for Waycar, from iOS 18 to herdr 0.7.5 or tmux 3.2, Node 20, OpenSSH and optional mosh.
- **Install Waycar on your Host** One command on your Mac or Linux machine finds herdr or tmux, installs the Waycar host tools, and offers to show a Pairing Code.
- **Pair with a Pairing Code** Scan or paste the Pairing Code your Host shows to add it to Waycar, with your key made on the device and the host key already pinned.
- **Add a Host by hand** Add a Host without a Pairing Code by typing its address, port and user, then choosing a Device Key, RSA Key or password to sign in.
- **Set up a Mac as a Host** Turn on Remote Login, install herdr or tmux and Node 20, then run the Waycar install command to use your Mac as a Waycar Host.
- **Set up a Linux Host** Install the OpenSSH server, herdr or tmux 3.2, and Node 20 on your Linux machine, then run the Waycar install command and pair.
- **Remove Waycar from a Host** Uninstall the Waycar host tools from a Mac or Linux Host, remove its Status Hooks and SSH key, and delete the Host in the app.

## The Console

- **The Console** The Console lists the agents and shells on all your Hosts in one place, sorted so the ones that need you come first.
- **Agent status** What Blocked, Done, Working, Idle, and Unknown mean on an agent card, and how status decides the Console's order.
- **Filter, search, and pin** Narrow the Console with Status pills, the Host and Workspace menus, and search, and pin the agents you want at the top.
- **Agent card fields** Choose which fields each Host's agent cards show in the Console, in up to three rows, from Settings › Agent List Fields.
- **Rename, close, and mark agents** Close, rename, move, pin, and mark agents from the Console, one at a time or several at once with Select.
- **Closed Sessions** When an agent exits or its tab closes, Waycar keeps it for 30 days so you can resume the same session with one tap.
- **Shells and busy shells** Plain shells show up in the Console as cards like agents, and a busy shell shows Running and the command it's running.
- **Workspaces** A Workspace groups the tabs on a Host, like a herdr workspace or a tmux session. Filter, move, and rename them from Waycar.
- **AI Summaries** AI Summaries add one AI-written sentence to each agent card and notification, saying what the agent is doing or what it needs.
- **AI Usage with CodexBar** See how much of your Claude, Codex, and other AI plan limits is left, read by CodexBar on your Host and shown atop the Console.

## Start and talk to agents

- **Start a new agent** Use the New Agent sheet to start a coding agent or a plain shell on any Host, in an existing Workspace or a new folder.
- **Start on a new worktree** Turn on New Worktree in New Agent to give an agent a fresh git checkout on its own branch, starting from the latest main.
- **The Composer** The Composer is a local draft box under an agent's terminal where you write a whole message, add files, and send it in one go.
- **Dictation** Speak a message to an agent instead of typing it. Waycar turns your speech into text on your device, on iOS 26 and later.
- **Snippets** Save the phrases you send an agent over and over, then insert one with a tap instead of typing it again.
- **Agent Skills** Browse the Skills and custom commands an agent has on your Host, read one, and insert its command into your message without sending.
- **Send photos and files** Attach up to 10 photos or files to a message. Waycar uploads them to your Host and adds their paths so the agent can open them.
- **Chat Mode** Talk to Claude Code, Codex, omp, pi and opencode as a simple chat instead of a terminal, with replies in your notifications.
- **New Chat from the Home Screen** Touch and hold the Waycar icon and tap New Chat to start a Chat Mode conversation right away, with the keyboard already up.

## The terminal

- **The live terminal** Open any agent or shell to see its real terminal on your iPhone or iPad, live from your Host, with taps for links, files, and keys.
- **Select and copy text** Touch and hold text in an agent's terminal to select it in place with draggable handles, then copy it with the system menu.
- **Scrolling and jump buttons** Drag to scroll an agent's history, jump to the start or back to live output, and step between the messages you sent.
- **The Toolbar** The bar at the bottom of every agent holds your keys, combos, actions, Snippets, and Custom Keys, and you choose and order them in Settings.
- **Type straight into the terminal** Direct Input sends every key you type straight to the agent's terminal, with a tools keyboard for Esc, Ctrl, arrows, and other keys.
- **Files and links** Tap a link or file path an agent prints to open it, preview images, PDFs, Markdown, and videos from your Host, and save media to Photos.
- **Terminal themes, fonts, and zoom** Pick a terminal theme for Light Mode and Dark Mode, choose a monospace font, and pinch to zoom the terminal's text size.
- **App icons** Choose Waycar's home-screen icon in Settings, from the caboose or the bare prompt mark, each in several colors.

## Hosts and connections

- **The Hosts sheet** See every Host as a card with its connection, latency, mosh or SSH badge, and live CPU, memory and swap gauges, and manage them.
- **A Host's page and checks** What each section of a Host's page does, how the Preflight checklist reads, and how to pick a herdr session or run the checks again.
- **mosh** Waycar runs agent terminals over mosh so they stay attached when you change networks, and falls back to SSH when mosh can't get through.
- **Network changes and reconnecting** What Waycar does when you switch networks, lose signal, or leave the app, and how your terminal comes back on its own.
- **Jump Host** Reach a machine that isn't on the open internet by connecting through an SSH Jump Host, with host keys checked at both hops.
- **Your desk and phone on one terminal** What happens to your desktop terminal when you open the same agent in Waycar, on herdr and on tmux, and how Take Over Here works on iPad.
- **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.
- **herdr vs tmux** Waycar works with herdr and with tmux 3.2 or later. Here is what each one supports, side by side, so you can pick or run both.
- **Waycar hooks for tmux** Small Status Hooks in Claude Code, Codex, omp, pi and opencode tell Waycar when a tmux agent is working, blocked or done.
- **The waycar command on your Host** Every waycar subcommand on your Host, from pair and status to hooks and notify, plus the herdr plugin actions Waycar adds.
- **SSH keys and passwords** Choose how Waycar signs in to a Host over SSH: a Device Key made on your phone, an RSA Key, or a password, and how to add the key on your Host.
- **Host keys and fingerprints** How Waycar checks that it's talking to your real machine, with the host key pinned by the Pairing Code or confirmed on first connect.

## Notifications

- **Notifications** Get a notification when an agent is Blocked or Done, encrypted on your Host so Waycar's push relay can't read what it says.
- **Live Activities** Follow each Host's agents on your Lock Screen and in the Dynamic Island, with counts of Blocked, Done, Working and Idle agents.

## iPad

- **Waycar on iPad** Use Waycar on iPad with the agent list in a sidebar beside the open terminal, a hardware keyboard, and drag and drop into the Composer.
- **Keyboard shortcuts** Use a hardware keyboard on iPad or iPhone to switch agents, search, start a new agent, open Hosts and Settings, and send.
- **Multiple windows and Stage Manager** Open Waycar in more than one iPad window, each on its own agent, and resize freely under Stage Manager.

## Settings and account

- **Settings at a glance** How to open Waycar's Settings on iPhone and iPad, what each row does, and where to find your version and open-source notices.
- **iCloud Sync** Keep your Hosts, SSH keys, trusted fingerprints and settings in step across your iPhone and iPad through end-to-end encrypted iCloud Keychain.
- **Waycar Pro and Launches** Waycar is free with 10 Launches in any rolling 30 days; Waycar Pro removes that limit and changes nothing else.
- **Privacy and analytics** What Waycar keeps on your device, what leaves it, and how to turn usage analytics and AI Summaries on or off.
- **Security** How Waycar protects your Hosts with on-device SSH keys, pinned host keys, checks at both Jump Host hops, and encrypted notifications.
- **Accessibility** How Waycar works with VoiceOver, Reduce Motion and larger text sizes, including the VoiceOver actions on cards, Hosts, the Toolbar and attachments.

## Troubleshooting

- **The install command fails** What each error and warning from the Waycar install command means, and how to fix it so the host tools install on your Host.
- **Can't connect to a Host** Fix a Host that won't connect, matched to the message Waycar shows in the Host's checks, from SSH errors to herdr and tmux setup.
- **What connection messages mean** What each Host connection message in the Console and over an open agent means, from Connecting and Paused to Host Unavailable and Session Ended.
- **mosh isn't connecting** Get mosh working when a Host shows SSH instead of MOSH or the mosh handshake fails. Install mosh-server and let UDP through.
- **Agent status shows Unknown** Why an agent shows Unknown instead of Working, Blocked or Done, and how to fix it with Waycar hooks on tmux or herdr's integrations.
- **Chat Mode won't start or send** Fix a Chat Mode chat that won't load, won't send, or shows no replies, from an outdated Waycar plugin to missing herdr integrations.
- **Notifications don't arrive** Fix missing Blocked and Done notifications by checking iOS permission, the Host's Notifications switch, the Waycar plugin, and the push relay.
- **Live Activities aren't updating** Find out why a Host's Live Activity doesn't appear or stops updating, using the Live Activity line in Waycar's notification settings.