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
- Menu says “Claude Code not found”: the
claudecommand-line tool is required; the Claude desktop app alone is not enough. See Troubleshooting / FAQ for the install command, then choose Recheck in the menu. - iCloud shows “Not signed in to iCloud”: open System Settings, sign in with the Apple ID that's on your iPhone, and turn on iCloud Drive. Then choose Recheck in the Setup guide.
- Menu shows “No workspace folder”: choose Choose… and pick the folder Claude may work in.
- Menu shows “Offline”: the Mac can't reach iCloud right now. Check its internet connection; the status turns to “Online” by itself.
- Sessions stop when the Mac sleeps: in System Settings → Energy, turn on Prevent automatic sleeping when the display is off, or keep the Mac plugged in.
- Uninstall: quit Walkabit from the menu bar and drag it from Applications to the Bin. Your settings are in
~/Library/Application Support/Walkabit.
Watch and iPhone
- Home screen shows “no Mac connected”: check that the iPhone and the Mac use the same Apple ID, and that the Mac's menu shows
Online. - No taps on the wrist: haptics only play during a workout or when Walkabit is open. Start a workout first.
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:
- Steps 1 to 3 must all be ticked and the menu-bar icon must say Online. Walkabit does not start work before that.
- Demo mode must be off on both the watch (gear) and the iPhone (Settings). Demo mode sends nowhere.
- 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
- Node.js 22.18 or newer (nodejs.org, LTS is fine). The installer checks and tells you if it is missing.
- The
claudecommand-line tool, installed and signed in with your own plan. The Claude desktop app (or its Code tab) is not enough: it does not install theclaudecommand. Check withwhich claude; if it prints nothing, runcurl -fsSL https://claude.ai/install.sh | bash, open a new Terminal window, runclaudeonce and complete/login. Walkabit never sees your Claude sign-in. - The Apple ID you use on your iPhone and Watch.
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:
- copies the relay to a fixed folder, so it does not depend on your Downloads folder
- checks that
claudeis installed and signed in - asks which folder the agents may work in (your workspace)
- opens the Sign in with Apple page for iCloud; use the Apple ID from your phone
- 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 folder | Service | |
|---|---|---|
| Linux | ~/.local/share/walkabit/app | systemd user service walkabit-relay |
| macOS | ~/Library/Application Support/Walkabit/app | LaunchAgent com.walkabit.relay |
| Windows | %LOCALAPPDATA%\Walkabit\app | Scheduled 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
- Status:
node <app folder>/src/cli.ts status, ordoctor --deepin place ofstatusto re-check everything, including a one-offclaude -p. - Health:
curl http://127.0.0.1:8787/v1/health - Logs: Linux
journalctl --user -u walkabit-relay -f; macOS~/Library/Logs/Walkabit/relay.log; Windows%APPDATA%\Walkabit\relay.log - “claude: command not found” in the logs: the service has its own PATH, built from where
claudeandnodewere found at install time. If you installed or moved Claude Code later, re-run the installer. - Sign-in page never comes back: on a remote machine, check that the
ssh -L 8788...tunnel is still open. - Relay stops when you log out (Linux): enable lingering, see above.
Command-line relay: uninstall
Settings and data are kept unless you add --purge (-Purge on Windows).
- Linux:
bash ~/.local/share/walkabit/app/packaging/linux/uninstall.sh --purge, thenrm -rf ~/.local/share/walkabit/app - macOS:
bash ~/Library/Application\ Support/Walkabit/app/packaging/macos/uninstall.sh --purge(removes the whole Walkabit folder) - Windows:
powershell -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\Walkabit\app\packaging\windows\uninstall.ps1" -Purge, then delete%LOCALAPPDATA%\Walkabit
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.