PP PocketPad

documentation

PocketPad app guide.

Everything needed to set up PocketPad, connect your iPhone to your Mac, customize keypad layouts, bind shortcuts, and use the CLI.

start setup learn editor
PocketPad Mac keypad editor showing a layout canvas and inspectors
PocketPad iPhone landscape keypad

overview

What PocketPad does

PocketPad turns an iPhone into a programmable control surface for a Mac. The macOS helper hosts a local pairing server, stores keypad profiles, and sends keyboard, pointer, or virtual gamepad output to the focused app. The iOS app displays the synced keypad and sends low-latency button, joystick, trigger, and trackpad input over your local network.

macOS

Helper + editor

Grant Accessibility, pair iPhones, manage profiles, record shortcuts, and edit each keypad visually.

iOS

Touch controller

Use synced profiles, switch setups, export keypads, toggle haptics, and make quick freeform layout edits.

CLI

Scriptable parity

Generate, import, export, select, bind, inspect, and test keypads from the terminal.

requirements

What you need

  • macOS 14 or newer running PocketPad Mac.
  • iOS 17 or newer running PocketPad on iPhone.
  • Same local network for Smart Connect, QR pairing, and realtime input.
  • Accessibility permission on Mac so PocketPad can inject keyboard and pointer events.
  • Local Network permission if iOS or macOS prompts for it.
  • Camera permission on iPhone only if you scan the Mac QR code.

setup

First-run setup

  1. Open PocketPad Mac.

    The Home screen shows readiness for Accessibility, the helper server, and iPhone pairing. A first-run setup guide walks through the same steps.

  2. Enable Accessibility.

    Click Request Accessibility Permission or Open Accessibility Settings, then enable PocketPad Mac in System Settings → Privacy & Security → Accessibility.

  3. Open PocketPad on iPhone.

    The iOS onboarding explains Local Network and Camera prompts. Tap Smart Connect, or use Scan Mac QR Code if this is the first pairing.

  4. Pair securely.

    Scan the QR code on the Mac, or manually enter a displayed ws://<mac-ip>:<port> address. If prompted, type the six-digit code shown on PocketPad Mac.

  5. Focus the target Mac app.

    After pairing, PocketPad controls whichever Mac app is currently focused. Use Release All if a key ever feels stuck.

mac app

Home, Keypad, and Settings

The Mac app is the source of truth for saved keypads and bindings. It runs the server, displays QR and manual pairing information, previews the active keypad, and exposes diagnostics.

Home

Use Home to check readiness, copy the pairing code, scan QR from the iPhone, switch profiles, make a setup the default, and perform quick local shortcut tests.

Keypad

Use Keypad to visually edit layouts, manage profiles, record shortcuts, configure output mode, and sync changes to the connected iPhone.

Settings

Use Settings for appearance defaults, input diagnostics, local addresses, server restart/stop, and advanced connection troubleshooting.

PocketPad Mac Keypad editor
Mac Keypad editor with setup list, canvas, and inspector.

ios app

Connection screen and controller screen

The iOS app starts on a connection screen unless it can reconnect to a trusted Mac or show a saved keypad offline.

Connection screen

Use Smart Connect for remembered Macs, scan a Mac QR code for first-time pairing, or manually enter host and port. You can also view the last synced keypad when offline.

Controller screen

The top bar shows connection status, the active keypad setup, edit lock, haptics and appearance settings, export actions, and Disconnect. Swipe down from the top edge if the bar is hidden.

Offline saved keypad

After a successful sync, iPhone can display saved profiles even when PocketPad Mac is closed. Input only controls the Mac while connected.

PocketPad iPhone portrait keypad
Portrait keypad with synced controls and top bar actions.

editor

Build a keypad setup

A setup is a saved profile containing layout, output mode, bindings, colors, haptics, style tokens, assets, and per-orientation variants. Edits on Mac save automatically and sync to the paired iPhone.

profiles

Setups and templates

Create, duplicate, delete, switch, import, export, and mark defaults. The active setup is sent to the iPhone and can be changed from either device.

canvas

Device frames

Match the editor to the connected iPhone, choose any supported iPhone display class, or use a custom canvas size. Portrait and landscape variants are saved separately.

layout

Controls and grid

Add buttons, joysticks, triggers, and trackpads. Drag on the canvas, nudge, align, distribute, layer, group, and use snap/grid preferences for precision.

design

Styles and haptics

Customize fills, strokes, pressed states, icons, glows, reusable style tokens, background fills, gradients, image fills, and per-control haptic patterns.

Typical editor workflow

  1. Choose a setup.

    Start from the default keypad, install a template, or generate/import a profile.

  2. Pick the device canvas.

    Use the connected iPhone frame or choose a model and orientation manually.

  3. Place controls.

    Add controls, resize them, and test hit targets with the preview.

  4. Record outputs.

    Select a control, click the shortcut field, press the desired Mac keystroke sequence, and pause to save.

  5. Sync and test.

    Connect the iPhone, focus the target Mac app, and press controls. Use Release All if you change apps mid-press.

outputs

Keyboard, pointer, and controller output

PocketPad can send multiple kinds of output depending on the selected profile and binding.

ModeUse it forNotes
KeyboardShortcuts, game keys, terminal workflows, app commandsRequires macOS Accessibility.
PointerTrackpad movement, clicking, right click, scrollingTrackpad controls inject CGEvent mouse and scroll events.
ControllerGames that recognize a system gamepadVirtual controller requires Apple-granted virtual HID entitlement.
CustomMixed keyboard + gamepad + pointer profilesBind each element or element part to the output you need.

Shortcut recording tips

  • Press Control + B to save a modifier combo like ⌃B.
  • Press a combo, release it, then press another key to create prefix sequences such as ⌃B H.
  • Modifier-only shortcuts save when you press and release the modifier key.
  • Use Default for one control or Reset All to restore starter bindings.

cli

Script PocketPad with pocketpad

The CLI mirrors the saved-configuration features in the Mac Keypad editor and adds runtime helper commands for automation and debugging.

pocketpad profile list --ids
pocketpad template list
pocketpad template install snes --name "SNES Browser Controls" --default
pocketpad profile export --all -o pocketpad-profiles.json
pocketpad profile import pocketpad-profiles.json
pocketpad binding set focus --sequence 'Control+B,H'
pocketpad output mode keyboard
pocketpad element add joystick --label "Right Stick" --up custom1 --down custom2 --left custom3 --right custom4
pocketpad element set jump --label A --shape circle --width 1.2 --height 1.2

Runtime helper commands

pocketpad app open
pocketpad status --json
pocketpad server restart
pocketpad pairing payload
pocketpad accessibility status
pocketpad test tap jump
pocketpad release-all

When PocketPad Mac is running, CLI profile, customization, and binding changes are pushed to the app via distributed notifications and then synced to the paired iPhone.

troubleshooting

Fix common setup issues

Smart Connect does not find my Mac

Make sure both devices are on the same Wi‑Fi network, PocketPad Mac is running, Local Network permission is allowed, and the Mac helper shows a local address. Use QR pairing as a fallback.

QR pairing fails

Confirm the iPhone camera permission is allowed. If the code still fails, manually enter one of the Mac helper's ws:// addresses and use the six-digit code shown on Mac.

Buttons press but nothing happens on Mac

Re-check Accessibility permission for PocketPad Mac, then refresh the permission status in the app. Also confirm the target Mac app is focused.

A key feels stuck

Tap Release All in the iPhone settings menu, the Mac Home quick actions, or run pocketpad release-all. PocketPad also releases held keys on disconnect, server stop, app background, and heartbeat timeout.

The virtual gamepad does not appear in games

Keyboard and pointer output work in normal builds. System-visible virtual controller output requires the app to be signed with Apple's com.apple.developer.hid.virtual.device entitlement.

safety

Local, authenticated, and recoverable input

  • Pairing uses a six-digit setup challenge and trusted reconnect token.
  • Input travels over the local network; Smart Connect advertises as _pocketpad._tcp.
  • Button state transitions use compact authenticated UDP frames with WebSocket mirroring for recovery.
  • macOS releases held keys after heartbeat timeout, disconnect, server stop, manual Release All, and app quit.
  • iOS sends a best-effort Release All when disconnecting, backgrounding, or becoming inactive.

faq

Frequently asked questions

Is PocketPad only for games?

No. It works well for games, but it is also useful for terminal shortcuts, tmux prefixes, Cursor commands, window management, browser actions, and any Mac app that accepts keyboard or pointer input.

Can I use it without the Mac app open?

The iPhone can view saved keypads offline, but controlling the Mac requires PocketPad Mac to be running and connected.

Can I back up my layouts?

Yes. Export keypads as JSON from iPhone or use pocketpad profile export --all from the CLI. Imports use the same versioned PocketPad keypad configuration envelope.

Can I make game-specific profiles?

Yes. Install templates, generate a profile from a known game, or create an agent-provided JSON spec and import it with the CLI.