Thumble app guide.

overview

What Thumble does

Thumble 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 or a nearby peer-to-peer path.

requirements

What you need

• macOS 14 or newer running Thumble Mac.
• iOS 17 or newer running Thumble on iPhone.
• Same local network or nearby peer-to-peer for Smart Connect, QR pairing, and realtime input.
• Accessibility permission on Mac so Thumble 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 Thumble 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 Thumble Mac in System Settings → Privacy & Security → Accessibility.

3. Open Thumble 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. For airplane/offline use, keep Wi‑Fi and Bluetooth enabled after enabling Airplane Mode so peer-to-peer discovery can run.

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 Thumble Mac.

5. Focus the target Mac app.

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

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.

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.

skins

Browse, install, and create visual themes

Thumble skins are shareable .pocketpad packages for appearance only. They can style backgrounds, native controls, icons, materials, pressed states, light/dark modes, and portrait/landscape variants. They cannot replace your geometry, labels, keyboard shortcuts, controller bindings, pointer actions, launch targets, or accessibility.

Create a directory-ready skin

Copy the starter under docs/skins/starter, give it a unique reverse-DNS identifier and semantic version, then use semantic roles such as movement, primary_action, menu, and trackpad instead of profile UUIDs.

cp -R docs/skins/starter MySkin
thumble skin validate MySkin
thumble skin pack MySkin -o MySkin.pocketpad
thumble skin validate MySkin.pocketpad --strict
thumble skin render MySkin.pocketpad --clean -o preview.png

Packages submitted to the public directory must pass strict validation, include a preview and license, use declared assets with SHA-256 hashes, and contain no executable files or profile bindings. See the repository’s complete format and security guide.

outputs

Keyboard, pointer, and controller output

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

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 Thumble with thumble

The CLI mirrors the saved-configuration features in the Mac Keypad editor and adds runtime helper commands for automation and debugging. Existing automation can continue using the thumbconsole and pocketpad compatibility executables.

If thumble is not already on PATH, build it from a source checkout to a predictable location:

xcodebuild -project Thumble.xcodeproj \
  -scheme ThumbleCLI \
  -destination 'platform=macOS' \
  -derivedDataPath build/DerivedData build
export PATH="$PWD/build/DerivedData/Build/Products/Debug:$PATH"
thumble --help

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

Runtime helper commands

thumble app open
thumble app screenshot -o /tmp/thumble-window.png --json
thumble status --json
thumble server restart
thumble pairing payload
thumble accessibility status
thumble test tap jump
thumble release-all

When Thumble Mac is running, CLI profile, customization, and binding changes are pushed to the app via distributed notifications and then synced to the paired iPhone. app screenshot captures only the largest visible Thumble window without activating the app or sending input events; it requires Screen Recording access for the terminal or agent host.

ChatGPT controller builder

Create a controller in conversation, approve it in Thumble

The public Thumble Controller Builder plugin creates portable controller drafts without connecting to your Mac. You do not need developer mode, a terminal, an MCP configuration file, or the alternate Rust host.

1. Describe.

   Tell ChatGPT the game or workflow, semantic Mac keys, orientation, and desired layout.

2. Preview.

   Review the controller rendered in ChatGPT and ask for revisions until the layout and bindings are right.

3. Download.

   Approve the preview and ask for the short-lived .thumblecontroller download.

4. Review locally.

   Open the file in Thumble Mac. Check every binding and layout finding, then choose Install as New Setup.

5. Select when ready.

   The import preserves existing setups and does not select or default itself. Choose it manually when you want to use it.

thumble controller review Controller.thumblecontroller --json
thumble controller review Controller.thumblecontroller --preview-output preview.png
thumble controller install Controller.thumblecontroller --yes

Artifacts contain semantic controls and key names only. They cannot include raw key codes, files, paths, images, credentials, application launch targets, shell commands, installed-profile operations, or input execution. Draft tokens expire after one hour and download links after ten minutes; ask ChatGPT to prepare a fresh download if needed.

See Create controllers in ChatGPT or controller import support.

ai agents

Tell an agent what you want, not how to click

Thumble includes a repository SKILL.md for terminal-capable agents. It explains how to choose between game generation, templates, targeted profile editing, layout repair, skin operations, and runtime diagnostics while avoiding unsafe UI automation.

Copy this starter prompt

Read /absolute/path/to/Thumble/SKILL.md, then use the
thumble CLI to create a landscape keypad for Celeste.
Research the default Mac keyboard controls, inspect my profiles,
and dry-run before installing. Preserve unrelated profiles,
validate the final layout, and report the source, confidence,
bindings, whether it became selected/default, and whether sync
could be confirmed. Do not use UI automation.

The reliable agent loop

1. Inspect.

   Run profile list, profile show active --json, and status --json before editing.

2. Preview.

   Use generate --dry-run, layout validate, and layout preview when available.

3. Apply.

   Make only the requested profile, binding, output, layout, or skin changes. Generation selects and defaults a profile unless the agent passes --no-select or --no-default.

4. Verify.

   Re-read the saved profile and bindings, rerun layout checks, and distinguish saved configuration from confirmed iPhone sync or physical-device feel.

Safe boundaries to include

• Use the CLI instead of clicking through the Mac or iPhone UI.
• Use thumble app screenshot for visual checks; do not activate the app or send keyboard/mouse events.
• Ask before launching apps, opening System Settings, triggering permission prompts, restarting the server, or sending test input.
• Treat test tap|down|up as real output to the currently focused Mac app, and use release-all if a test is interrupted.
• Inspect before deleting/resetting profiles, removing skins, clearing bindings, or replacing output modes. Export all profiles before a broad migration or reset.
• For handcrafted community skins, require editable source, native-rendered review evidence, independent critique/QA, and explicit human approval before publication.

See the complete Using Thumble with an AI agent guide for reusable instruction-file snippets and copy-paste prompts for games, productivity pads, layout repair, diagnostics, and skin installation.

troubleshooting

Fix common setup issues

safety

Local, authenticated, and recoverable input

• Pairing uses a six-digit setup challenge and trusted reconnect token.
• Input travels over the local network or nearby peer-to-peer; 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