# Waycar Help

How to set up and use Waycar, the iPhone and iPad app for coding agents in herdr and tmux. One page per feature. Each link is the page as Markdown; the same URL without `.md` is the web page. Web index: https://waycar.dev/help

## Get started

- [What is Waycar?](https://waycar.dev/help/what-is-waycar.md): 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](https://waycar.dev/help/requirements.md): 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](https://waycar.dev/help/install.md): 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](https://waycar.dev/help/pairing.md): 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](https://waycar.dev/help/add-host-manually.md): 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](https://waycar.dev/help/mac-host.md): 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](https://waycar.dev/help/linux-host.md): Install the OpenSSH server, herdr or tmux 3.2, and Node 20 on your Linux machine, then run the Waycar install command and pair.
- [Update Waycar on your Host](https://waycar.dev/help/update-host-tools.md): Run the install command again to update the Waycar plugin and host tools on your Host, add hooks for new agents, and pair another device.
- [Remove Waycar from a Host](https://waycar.dev/help/remove-host-tools.md): 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](https://waycar.dev/help/console.md): 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](https://waycar.dev/help/agent-status.md): What Blocked, Done, Working, Idle, and Unknown mean on an agent card, and how status decides the Console's order.
- [Filter, search, and pin](https://waycar.dev/help/filter-search-pin.md): 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](https://waycar.dev/help/agent-card-fields.md): 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](https://waycar.dev/help/manage-agents.md): Close, rename, move, pin, and mark agents from the Console, one at a time or several at once with Select.
- [Closed Sessions](https://waycar.dev/help/closed-sessions.md): 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](https://waycar.dev/help/shells.md): Plain shells show up in the Console as cards like agents, and a busy shell shows Running and the command it's running.
- [Workspaces](https://waycar.dev/help/workspaces.md): 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](https://waycar.dev/help/ai-summaries.md): 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](https://waycar.dev/help/ai-usage.md): 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](https://waycar.dev/help/new-agent.md): 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](https://waycar.dev/help/worktrees.md): Turn on New Worktree in New Agent to give an agent a fresh git checkout on its own branch, starting from the latest main.
- [Supported agents](https://waycar.dev/help/supported-agents.md): The coding agents Waycar can find and start from New Agent, which ones work in Chat Mode, and how Waycar finds them on a Host.
- [The Composer](https://waycar.dev/help/composer.md): 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](https://waycar.dev/help/dictation.md): 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](https://waycar.dev/help/snippets.md): Save the phrases you send an agent over and over, then insert one with a tap instead of typing it again.
- [Agent Skills](https://waycar.dev/help/skills.md): 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](https://waycar.dev/help/send-files.md): 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.
- [Queued messages](https://waycar.dev/help/queued-messages.md): A message you send while your Host is offline waits on your phone as Queued and goes out by itself when the Host is back.
- [Chat Mode](https://waycar.dev/help/chat-mode.md): Talk to Claude Code, Codex, omp, pi or opencode as a simple chat instead of a terminal, with replies in your notifications.
- [New Chat from the Home Screen](https://waycar.dev/help/new-chat.md): 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](https://waycar.dev/help/terminal.md): 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](https://waycar.dev/help/select-copy.md): 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](https://waycar.dev/help/scrolling.md): 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](https://waycar.dev/help/toolbar.md): 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](https://waycar.dev/help/direct-input.md): 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](https://waycar.dev/help/files-and-links.md): 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](https://waycar.dev/help/terminal-appearance.md): 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](https://waycar.dev/help/app-icons.md): 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](https://waycar.dev/help/hosts.md): 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](https://waycar.dev/help/host-page.md): 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](https://waycar.dev/help/mosh.md): 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](https://waycar.dev/help/reconnecting.md): What Waycar does when you switch networks, lose signal, or leave the app, and how your terminal comes back on its own.
- [Jump Host](https://waycar.dev/help/jump-host.md): 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](https://waycar.dev/help/take-over.md): 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](https://waycar.dev/help/tmux.md): 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](https://waycar.dev/help/herdr-vs-tmux.md): 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](https://waycar.dev/help/tmux-hooks.md): 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](https://waycar.dev/help/waycar-command.md): 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](https://waycar.dev/help/ssh-keys.md): 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](https://waycar.dev/help/host-keys.md): 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](https://waycar.dev/help/notifications.md): 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](https://waycar.dev/help/live-activities.md): Follow each Host's agents on your Lock Screen and in the Dynamic Island, with counts of Blocked, Done, Working and Idle agents.

## iPad and CarPlay

- [Waycar on iPad](https://waycar.dev/help/ipad.md): 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](https://waycar.dev/help/keyboard-shortcuts.md): 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](https://waycar.dev/help/multiple-windows.md): Open Waycar in more than one iPad window, each on its own agent, and resize freely under Stage Manager.
- [CarPlay](https://waycar.dev/help/carplay.md): See your agents on the car's screen and talk to them out loud with CarPlay, with spoken answers and nothing agent-written on screen.
- [Approve commands by voice](https://waycar.dev/help/carplay-voice.md): In CarPlay, allow or deny a Claude Code or Codex command approval out loud, and leave risky or long commands for later.

## Settings and account

- [Settings at a glance](https://waycar.dev/help/settings.md): 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](https://waycar.dev/help/icloud-sync.md): 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](https://waycar.dev/help/waycar-pro.md): Waycar is free with 10 Launches in any rolling 30 days; Waycar Pro removes that limit and changes nothing else.
- [Privacy and analytics](https://waycar.dev/help/privacy.md): What Waycar keeps on your device, what leaves it, and how to turn usage analytics and AI Summaries on or off.
- [Security](https://waycar.dev/help/security.md): How Waycar protects your Hosts with on-device SSH keys, pinned host keys, checks at both Jump Host hops, and encrypted notifications.
- [Accessibility](https://waycar.dev/help/accessibility.md): 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](https://waycar.dev/help/install-fails.md): 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](https://waycar.dev/help/cant-connect.md): 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](https://waycar.dev/help/connection-messages.md): 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](https://waycar.dev/help/mosh-not-connecting.md): 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](https://waycar.dev/help/status-unknown.md): 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](https://waycar.dev/help/chat-mode-troubleshooting.md): Fix a Chat Mode chat that won't load, won't send, or shows no replies, from an outdated Waycar plugin to opencode setup and trust prompts.
- [Notifications don't arrive](https://waycar.dev/help/notifications-not-arriving.md): 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](https://waycar.dev/help/live-activities-not-updating.md): Find out why a Host's Live Activity doesn't appear or stops updating, using the Live Activity line in Waycar's notification settings.
- [CarPlay voice isn't working](https://waycar.dev/help/carplay-voice-not-working.md): Fix CarPlay voice problems in Waycar, from missing microphone access and speech models to iOS versions older than 26.4.
- [Get help and contact support](https://waycar.dev/help/get-help.md): Read help in the app, email Waycar support or ask the r/waycar community from Settings, and what to include so we can help quickly.