Thumble's macOS editor has a command-line counterpart designed for coding agents and automation. An agent can create and revise keypad profiles, bind shortcuts, validate layouts, install skins, inspect the running Mac helper, and sync changes to a paired iPhone without driving the UI.
This guide is for users who want to tell an agent such as Pi, Claude Code, Codex, or another terminal-capable assistant to configure Thumble on their behalf.
Give the agent these inputs:
- The
thumbleexecutable, either onPATHor at a known absolute path. - This repository's
SKILL.md, which documents the full agent workflow and command surface. - A concrete outcome, including the target app or game, important controls, and whether the agent may install/select the result.
A good request is outcome-focused:
Use Thumble to create a landscape keypad for Celeste. Research the default Mac keyboard controls, keep movement on the left and actions on the right, dry-run the profile first, install and select it, validate both orientations, and report the final bindings. Read
/path/to/Thumble/SKILL.mdbefore using the CLI.
You do not need to translate the request into CLI commands. The skill teaches the agent how to inspect the current setup, choose the right workflow, and verify its work.
Include the absolute path to SKILL.md in your prompt:
Before working on Thumble, read /absolute/path/to/Thumble/SKILL.md
and follow its inspection, dry-run, safety, and verification guidance.
This is the simplest option when the agent can read local files.
Add this to the instruction file your agent already reads, such as AGENTS.md or CLAUDE.md:
## Thumble
When a task involves an iPhone keypad, Mac shortcuts, game controls, or
Thumble runtime diagnostics, read `/absolute/path/to/Thumble/SKILL.md`
and use the `thumble` CLI. Inspect before editing, preview or dry-run when
available, avoid UI automation, and verify the saved profile after changes.Tools that discover SKILL.md directories can use the repository skill directly or copy it into their documented project/user skill directory. For example, if your tool follows the .agents/skills convention:
mkdir -p .agents/skills/thumble
cp /absolute/path/to/Thumble/SKILL.md \
.agents/skills/thumble/SKILL.mdUse the skill directory documented by your agent host if it expects a different location. Keep the copied skill updated when Thumble adds commands.
The repository also ships an installable ChatGPT/Codex plugin at plugins/thumble that bundles the keypad-generator skill together with the local thumble-mcp stdio server (typed profile, layout, binding, and runtime tools). A repo marketplace at .agents/plugins/marketplace.json exposes it:
- Restart the ChatGPT desktop app with this repository checked out (or run
codex plugin marketplace add /absolute/path/to/Thumble). - Open Plugins in the sidebar, choose the Thumble (repo marketplace) source, and install Thumble.
The bundled MCP launcher finds the adapter via $THUMBLE_MCP_BINARY, the Thumble Host app bundle, or PATH. Input and configuration writes stay disabled unless explicitly enabled. See plugins/thumble/README.md and docs/rust-host.md for details, security defaults, and the remote relay option for ChatGPT chat-side connectors.
First ask the agent to check whether the CLI is already available:
command -v thumble
thumble --helpFrom a Thumble source checkout, build to a predictable location:
xcodebuild -project Thumble.xcodeproj \
-scheme ThumbleCLI \
-destination 'platform=macOS' \
-derivedDataPath build/DerivedData \
build
export THUMBLE_CLI="$PWD/build/DerivedData/Build/Products/Debug/thumble"
"$THUMBLE_CLI" --helpThe build also produces thumbconsole and pocketpad compatibility executables, but new instructions should use thumble.
Ask the agent to follow this loop for reliable, reviewable changes.
thumble --help
thumble profile list --ids
thumble profile show active --json
thumble status --jsonprofile commands can inspect saved configuration while the Mac helper is closed. Runtime status and syncing require Thumble Mac to be running.
| Goal | Preferred command |
|---|---|
| Known game with a built-in generator | generate "Game Name" --dry-run |
| Unknown game | Research controls, write a JSON spec, then generate --spec FILE --dry-run |
| Familiar console/emulator layout | template list, then template install |
| Productivity or app shortcuts | profile create, element, and binding |
| Revise an existing keypad | profile show, then targeted element, binding, or output changes |
| Fix spacing or touch targets | layout validate, layout fix, and layout preview |
| Apply an existing visual skin | skin inspect, skin validate, then skin import / skin apply |
| Diagnose the Mac helper | status, monitor, latency, server, pairing, or accessibility |
For generated profiles, remember that generate installs, selects, and makes the new profile the default unless the agent passes --no-select or --no-default. The dry-run summary also lists every control's rendered point size on the reference canvas, so the agent can confirm buttons are thumb-sized before installing.
Use the non-mutating path whenever one exists:
thumble generate --spec /tmp/game-keypad.json --json --dry-run
thumble layout validate --profile "My Keypad" --json
thumble layout preview --profile "My Keypad" \
--variant landscape \
-o /tmp/my-keypad-landscape.pngFor unknown games, the spec should identify its source and use an honest high, medium, or low confidence value. A low-confidence but playable mapping is better than silently presenting guessed controls as fact.
When the prompt clearly asks the agent to create, install, select, or update a keypad, it may make that scoped change after previewing it. It should avoid unrelated profile, default, output-mode, or appearance changes.
When Thumble Mac is running, saved CLI changes are reloaded and synced to the paired iPhone. The iPhone may still show the saved profile offline when the helper is closed, but it cannot control the Mac until reconnected.
thumble profile show active --json
thumble layout validate --profile active --json
thumble binding display --profile active --json
thumble status --jsonA useful final report names the profile, confidence/source when relevant, final bindings, layout validation result, whether it was selected/defaulted, and whether sync could be confirmed.
Replace paths and names before sending these to your agent.
Read /absolute/path/to/Thumble/SKILL.md, then use the thumble CLI to
create a keypad for [GAME]. Look up the default Mac keyboard controls from a
reliable source. Dry-run before installing. Put movement on the left, frequent
actions within easy right-thumb reach, and pause/menu away from primary actions.
Make controls thumb-sized — primary actions at least ~90pt rendered, nothing
under 66pt (check the dry-run size table). Install and select the profile, but
do not replace unrelated profiles. Validate the layout and summarize the source,
confidence, bindings, control sizes, and validation result.
Read /absolute/path/to/Thumble/SKILL.md and create a Thumble profile
named "[NAME]" for [APP]. I need controls for [LIST OF ACTIONS/SHORTCUTS]. Keep
labels short, use a trackpad only if it helps this workflow, attach the app at
[APP PATH] only if it exists, and preserve my current default profile. Preview
and validate the layout, then show me exactly what changed.
Read /absolute/path/to/Thumble/SKILL.md. Inspect my Thumble profile
"[PROFILE]" without changing it first. Validate portrait and landscape layouts,
then fix only touch-target, overlap, edge, size, and thumb-reach issues. Preserve
all bindings, labels, output modes, and the current default. Render layout
previews and report each repair plus any issue that remains.
Read /absolute/path/to/Thumble/SKILL.md. Diagnose Thumble without UI
automation. Inspect status and accessibility, then use the synthetic latency
compare/verify commands before suggesting physical-device capture. Do not restart
the server, open System Settings, launch apps, or send test input unless I approve
that action. Summarize evidence separately from recommendations.
Read /absolute/path/to/Thumble/SKILL.md. Inspect and strictly validate
[PACKAGE.pocketpad], explain what it can style and any warnings, then apply it to
"[PROFILE]" only. Preserve geometry, labels, bindings, launch targets, and output
mode. Do not publish or submit the skin anywhere.
Handcrafted skin creation has a stricter art-direction, editable-source, native-render, critique, QA, and human-approval workflow. Agents should also read docs/skins/README.md and use the project thumble-skin-author skill before authoring or revising a community skin.
Tell the agent about any stricter boundaries you want. The repository skill uses these defaults:
- Prefer CLI inspection and mutation over clicking through the Mac or iPhone UI.
- Use
thumble app screenshotfor visual verification. It captures a Thumble window without activating it or sending keyboard/mouse events. - Do not launch Thumble Mac, open System Settings, or trigger permission prompts without user permission because those actions can change focus or interrupt work.
- Treat
test tap,test down, andtest upas real input: they invoke the selected control's configured output in the focused Mac app. - Use
release-allif a test is interrupted or a held input is uncertain. - Inspect before destructive commands such as profile deletion/reset, skin removal, binding reset, or output-mode replacement. Export a backup with
profile export --allbefore a broad migration or reset. - Do not print or publish pairing codes, trusted reconnect material, private app paths, or captured diagnostics unless the user requested them.
- Never claim that a skin was approved or publish one without explicit human approval of the exact review artifact and package hash.
An agent can verify saved profiles, bindings, output mappings, layout-health checks, rendered previews, Mac helper state, accessibility status, and synthetic latency assumptions from the CLI.
An agent cannot infer that physical iPhone input feels good from a rendered preview or synthetic replay. Final ergonomic judgment, real network latency, game recognition, and virtual-controller availability may require the paired device, the target app, and a human test. Ask the agent to state these limits instead of claiming success from configuration alone.
thumble: command not found: Give the agent the absolute binary path or let it build the CLI from the source checkout.- The agent keeps trying to click the app: Explicitly require
SKILL.md, CLI-only operation, andapp screenshotfor visual checks. - A new profile unexpectedly became the default: Generation defaults to install + select + default. Request
--no-defaultand optionally--no-select. - An unknown game fails generation: Ask the agent to research or infer controls and provide a JSON spec instead of inventing a hidden fallback.
- Changes do not appear on iPhone: Saved changes can still be valid. Thumble Mac must be running and the iPhone paired for immediate sync.
- Screenshot verification fails: Screen Recording access must already be granted to the terminal or agent host. Do not ask the agent to bypass the permission with screen-control automation.
- Controller mode does not appear in a game: System-visible virtual gamepad output requires Apple's virtual HID entitlement. Keyboard and pointer output can still work.
For the full command reference and agent decision tree, use SKILL.md. For ordinary app setup and editor usage, return to the main README or the website documentation.