Back to Pocket Dev

Pocket Dev docs

Install on macOS

Contents

Install Pocket Dev on macOS

Prefer your coding assistant? Copy the setup prompt and paste it into an agent running on your Mac. AI setup details.

Run the commands in Terminal (Cmd+Space, type Terminal, Enter).

1. Prerequisites

  • Node.js 22 or newer. With Homebrew: brew install node. Or the LTS installer from nodejs.org.
  • A phone on the same Wi-Fi as the Mac.
node -v
npm -v

You should see v22 or higher, then an npm version.

2. Install

Keep the @anisirji/ and the -g:

npm install -g @anisirji/pocket-dev
pocket-dev doctor

If the install fails while building node-pty, run xcode-select --install once, then repeat. pocket-dev doctor checks Node, npm's global folder on PATH, the command, terminals, tools and port 7777, and prints the exact fix for each cross.

Installing also adds a Pocket Dev Admin tile with the Pocket Dev logo to your Dock (it builds ~/Applications/Pocket Dev Admin.app and restarts the Dock once, so the Dock flickers). It is a one-click way to the Admin page. This is the one change the install makes without asking. Undo: pocket-dev admin unpin. Skip: POCKET_DEV_NO_PIN=1 or npm install -g --ignore-scripts; pocket-dev setup still offers it.

3. Start

pocket-dev start

You should see a QR code, then:

Pocket Dev running at http://192.168.1.20:7777
Password: Xk3p9QwR2tLm

The password is shown once, so copy it. The Admin page opens in the Mac's browser (add --no-open to stop that). On your phone, scan the QR code with the camera, or open the address and type the password. Missed the address? ipconfig getifaddr en0 prints it (try en1 if en0 prints nothing).

4. Firewall and permissions

  • If macOS asks whether node may accept incoming connections, choose Allow. If you chose Deny, open System Settings, Network, Firewall, Options, and allow node.
  • Screen view needs Screen Recording permission for the program that runs Pocket Dev (Terminal, VS Code, or node for the background service). pocket-dev admin, Permissions panel, opens the right page. Without it the screen view shows only the wallpaper.

5. Optional tools

Chats need at least one of Claude Code or Codex. pocket-dev setup --check lists what is missing; pocket-dev setup shows each command before running it.

ToolInstallLog in
Claude Codenpm install -g @anthropic-ai/claude-codeclaude auth login
Codexnpm install -g @openai/codexcodex login
Gitbrew install git, or xcode-select --installnone
GitHub CLI (gh)brew install ghgh auth login
cloudflared (internet access only)brew install cloudflarednone for a Quick link

Experimental: Google Antigravity CLI (agy) in Chat. Pocket Dev starts agy acp and talks to it over the Agent Client Protocol. It was tested by hand on macOS with Antigravity CLI 1.5.9. Google has not said whether starting agy from another app is allowed. See the roadmap.

Experimental: GitHub Copilot CLI (copilot) in Chat. Pocket Dev starts copilot --acp --stdio and talks to it over the Agent Client Protocol, with the sign-in that copilot login made. It was tested on macOS with Copilot CLI 1.0.112. See the roadmap.

6. Keep it running, start at login

pocket-dev service install
pocket-dev service status

This installs a launchd agent (~/Library/LaunchAgents/dev.pocket.server.plist) that starts at login. Other commands: service restart, service logs, service uninstall, service autostart on|off|status.

7. Update and uninstall

npm install -g @anisirji/pocket-dev@latest
pocket-dev service restart
pocket-dev service uninstall
npm uninstall -g @anisirji/pocket-dev

Settings stay in ~/.pocket-dev until you delete that folder.

Errors and fixes

You seeCause and fix
unknown command 'start'. See 'main --help', or EEXIST on installA different npm package named pocket-dev owns the command. npm uninstall -g pocket-dev, then npm install -g @anisirji/pocket-dev.
command not found: pocket-devYou skipped -g, or the terminal predates the install. Open a new terminal. npm config get prefix shows npm's global folder; its bin must be on PATH. Or run npx -y @anisirji/pocket-dev doctor.
404, or it installs from GitHubUse the scoped name with the @: @anisirji/pocket-dev.
EACCES writing npm's global folderDo not use sudo. Install Node with Homebrew, nvm or fnm so npm writes to your home folder.
node-pty fails to buildxcode-select --install, then pocket-dev doctor --fix.
"Terminals are not available on this computer"pocket-dev doctor --fix, then restart Pocket Dev.
The phone cannot open the addressSame Wi-Fi (not mobile data or an isolated guest network)? node allowed in the firewall? Use the numeric address, not localhost. Run pocket-dev doctor.
Port 7777 is in usepocket-dev start --port 7780, or pocket-dev config set port 7780. A stray copy: pocket-dev service install --force takes the port over.
Forgot the passwordpocket-dev admin, then Password.
Screen view shows only the wallpaperAllow Screen Recording, see step 4.

More: full guide, reference.

Read from docs/macos.md in the repository and refreshed about once an hour.