Support

Stuck? Email support@walkabit.dev. Include your macOS version, what the menu bar icon says, and what you tried.

Walkabit for MacWatch and iPhoneTroubleshooting / FAQAdvanced: command-line relay

Walkabit for Mac

Watch and iPhone

Troubleshooting / FAQ

“Quota exceeded” or “iCloud storage is full”. Walkabit keeps its data in your private iCloud database, which counts against your iCloud storage. When your iCloud is full, nothing can be saved: no tasks, sessions or heartbeats, from the Mac, iPhone or watch. Free up space or upgrade your plan in System Settings > Apple ID > iCloud, then quit and reopen Walkabit. The Mac app shows this as “iCloud storage is full”; in the Mac log it appears as Quota exceeded.

The Mac app says Claude Code is not found, but I have the Claude app

Walkabit runs the claude command-line tool. The Claude desktop app (or its Code tab) does not install it, so it is not enough. In Terminal, check with:

which claude && claude --version

If nothing prints, install it:

curl -fsSL https://claude.ai/install.sh | bash

Then open a new Terminal window, run claude once and sign in, and click Recheck in Walkabit. The installer puts it in ~/.local/bin, which Walkabit searches.

Step 1 says “Not signed in to iCloud”

The Mac needs to be signed in to iCloud with the same Apple ID as your iPhone and watch, with iCloud Drive on. The Mac’s macOS version is rarely the cause. Open System Settings > Apple ID: if there is no iCloud row, or Devices says “Failed to load devices”, the sign-in is half-broken. Sign out and back in (or restart), then turn iCloud Drive on. If the Apple ID password is the blocker, you can reset it from your iPhone under Settings > your name > Sign-In & Security > Change Password.

Step 4 never ticks after I send a task from the watch

Work through these in order:

  1. Steps 1 to 3 must all be ticked and the menu-bar icon must say Online. Walkabit does not start work before that.
  2. Demo mode must be off on both the watch (gear) and the iPhone (Settings). Demo mode sends nowhere.
  3. Check that your iCloud storage is not full (see the note above).

If it still does not tick, email support with what you see.

The watch opens the keyboard instead of dictation

Walkabit records your voice itself when you tap New task or Reply: speak, then tap ■ stop. Your iPhone turns the clip into text on the device and sends it back for you to review. If the iPhone is not in range or does not answer, Walkabit falls back to the watch’s own text field, and a line above it says why. Apps cannot force that text field to start with dictation, and the watch remembers the last input method you used, so tap the microphone once there to switch back. You can also check Settings > Input > Voice input on the watch.

For the recorder, speech access must be allowed on the iPhone (Walkabit asks at first launch; later in iPhone Settings > Walkabit), and Dictation must be on in iPhone Settings > General > Keyboard.

A send fails

Your prompt is not lost. The iPhone keeps what you typed and shows couldn’t send with the reason and a retry button. The watch keeps the prompt on its review screen with retry. Fix the reason, usually being offline, being signed out of iCloud, or full iCloud storage, and tap retry.

“Service Unavailable”, “busy” or “throttled”

iCloud is rate-limiting or briefly down. Walkabit retries on its own. If it persists, check Apple’s system status.

Advanced: command-line relay

Unsupported. For servers, Linux boxes and people who'd rather not install a Mac app. Linux is the best-tested; the Windows installer is unverified. Most people should use Walkabit for Mac.

The relay is a small program that runs the official claude CLI for your watch and phone. It needs Node.js 22.18 or newer.

Before you start

Install

Linux or macOS, in a terminal:

curl -fsSL https://walkabit.dev/install.sh | bash

Windows, in PowerShell:

irm https://walkabit.dev/install.ps1 | iex

These small scripts download the relay package from walkabit.dev/downloads, check its checksum, unpack it and run its own installer. You can read them first: install.sh, install.ps1. Prefer to do it by hand? Download the package, extract it and run ./install.sh (or powershell -ExecutionPolicy Bypass -File .\install.ps1 on Windows).

The installer then:

  1. copies the relay to a fixed folder, so it does not depend on your Downloads folder
  2. checks that claude is installed and signed in
  3. asks which folder the agents may work in (your workspace)
  4. opens the Sign in with Apple page for iCloud; use the Apple ID from your phone
  5. installs and starts the background service, then prints a health check

Useful options: --workspace DIR, --no-browser (print the sign-in URL instead of opening it), --no-service (print the command to run it yourself), --yes (no prompts). Pass them after bash -s --:

curl -fsSL https://walkabit.dev/install.sh | bash -s -- --workspace ~/code --no-browser

On Windows, pass options like this:

& ([scriptblock]::Create((irm https://walkabit.dev/install.ps1))) --workspace C:\code

Re-running the installer upgrades in place. Your settings, iCloud sign-in and relay token are kept.

App folderService
Linux~/.local/share/walkabit/appsystemd user service walkabit-relay
macOS~/Library/Application Support/Walkabit/appLaunchAgent com.walkabit.relay
Windows%LOCALAPPDATA%\Walkabit\appScheduled Task WalkabitRelay (at logon)

Headless box (server, no screen)

The Apple sign-in redirects your browser to http://localhost:8788 on the machine running the relay. From your own computer, tunnel that port and install with --no-browser:

ssh -L 8788:127.0.0.1:8788 you@server
curl -fsSL https://walkabit.dev/install.sh | bash -s -- --no-browser

Open the printed sign-in URL in the browser on your computer. The tunnel carries the redirect back to the relay.

Linux: keep it running after you log out

A systemd user service stops when you log out unless lingering is on (needs root once):

sudo loginctl enable-linger $USER

Command-line relay: check and troubleshoot

Command-line relay: uninstall

Settings and data are kept unless you add --purge (-Purge on Windows).

Contact

Email support@walkabit.dev. For the command-line relay, include your OS, the output of the status command and the last lines of the relay log. Please remove anything private first.