Install
Docs

Get afk running.

Five minutes, start to finish. Everything below is also in afk help.

Requirements

  • macOS with Zed, and Claude Agent and/or Codex added in Zed's Agent panel.
  • An Android phone. The iPhone app is coming to the App Store.
  • Optional: Tailscale on the Mac and the phone, to reach your Mac from anywhere. Without it, afk works on the same Wi-Fi.

You don't need Node.js installed: the installer downloads its own copy if yours is missing or older than 22.18.

Install on the Mac

curl -fsSL https://goafk.dev/install.sh | sh

The installer only touches your home folder. It:

  1. uses your Node.js 22, or downloads a checksum-verified private copy into ~/.afk/runtime;
  2. installs afk into ~/.afk and adds the afk command to ~/.local/bin;
  3. runs afk setup, which syncs Zed's agents, starts the hub in the background, makes the Mac reachable (Tailscale on port 8443 and/or your Wi-Fi), checks everything, and prints a pairing QR code.

If setup says so, quit and reopen Zed once so running agents start syncing. Want to read the script first? It's at /install.sh.

Get the app

afk for Android is available as an APK while the Google Play listing is on its way; the App Store version follows. Download links appear here as soon as each is live.

Pair your phone

  1. Open afk. On first launch it shows Connect your Mac.
  2. Scan the QR code from afk setup, or run afk pair for a new one. You can also scan it with the phone's camera, or copy the link and tap Paste pairing link.
  3. That's it: your projects and threads appear.

Codes work once and expire after 15 minutes. Each phone gets its own key; the Mac's master key never leaves the Mac.

Several Macs

Install afk on each Mac, then in the app tap the Mac's name at the top of the sidebar → Add a Mac and scan that Mac's code. The switcher shows one Mac at a time and badges the others when they need you. Rename Macs from the same sheet.

Commands

CommandWhat it does
afk setupSync Zed's agents, start the hub, check everything, show a pairing code. Safe to re-run.
afk pairA new pairing code for another phone.
afk devicesPaired phones and when each was last seen.
afk devices revoke <id>Cut one phone off.
afk statusHub health and connected agents.
afk threadsList synced threads.
afk send <thread> "…"Send a message into a thread (it shows in Zed).
afk new <project> claude "…"Start a new thread in Zed.
afk watchStream live events.
afk permissionsOne-time macOS permission so afk can open new threads in Zed.
afk uninstallRemove everything setup added.

Troubleshooting

The app can't reach my Mac

Make sure the Mac is awake. At home, the phone must be on the same Wi-Fi; away, Tailscale must be on for both. Run afk setup again: it reports which addresses work.

A thread shows as read-only

Its agent process isn't running. Open the thread in Zed, or tap Continue here in the app to load it into a running agent.

"Tailscale Serve could not start"

Tailscale asks you once to enable HTTPS / Serve for your tailnet. Follow the link setup prints, then run setup again.

New threads from the phone don't open

Zed must be running, and afk needs a one-time macOS permission: run afk permissions.

Uninstall

afk uninstall          # removes the Zed settings blocks and the background service
rm -rf ~/.afk ~/.local/bin/afk

Your Zed settings were backed up to ~/.afk/backups before every change.