New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Macro Deck 3 plugin that builds phone macropad decks for host operations with a private git backup.

version
1.0.0
GitHub stars
32
View on GitHub

What it does

  • Adds skills for setup-host, connect-mcp, build-deck, icon-packs, adb-actions, and restore-decks, plus save-decks and archive-backup for snapshots
  • Covers the full setup path: install the host, register its MCP server, verify tools, then build decks from a spec
  • Enforces dry runs before changes and favors host-side HTTP API calls over keystrokes that depend on window focus
  • Designed for Linux users who want a phone deck controlled by Claude Code, with decks stored in a private repo

Turn a phone into a macropad for host operations with Macro Deck 3: install the host, connect its MCP server, build decks from a spec, and keep decks in a private git repo.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install macro-deck@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

ADB actions on deck buttons

The Macro Deck host runs the button's command; the command drives an Android device over adb. Every action goes through scripts/adb-deck.sh (this plugin), which finds the device each time, so a wireless-debugging port that changed since yesterday does not break the button.

Requires: adb and, for wireless reconnect, avahi-browse (package avahi-utils) on the host; the device paired with this host once (Developer options → Wireless debugging → Pair, or USB with debugging authorised). Pairing is not this skill: use an adb pairing skill or adb pair <ip>:<pairing-port> <code>.

1. Device config (once per host)

Optional user-data file, never in a repo: ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/macro-deck/adb.json

{"ip": "<phone LAN IP>"}

ip limits wireless reconnect to that phone when several devices advertise debugging. serial pins one device. With neither, the only connected device is used. Check with scripts/adb-deck.sh connect.

2. Pick the action

Take it from references/adb-actions.md. Only confirmed entries go on a button without testing; an untested one is run by hand against the device first and then moved to confirmed (step 4).

3. Build the button

Use build-deck with a Run Command block (app.macro-deck.system / run-command, shell: bash):

{"type": "action", "blockType": "app.macro-deck.system.run-command", "label": "Run Command",
 "integrationId": "app.macro-deck.system", "actionId": "run-command",
 "parameters": [
   {"name": "shell", "type": "choice", "label": "Shell", "value": "bash"},
   {"name": "command", "type": "string", "label": "Command",
    "value": "<absolute path to the plugin>/scripts/adb-deck.sh launch app.macrodeck.companion"},
   {"name": "timeout", "type": "number", "label": "Timeout", "value": 15000}]}

Use the absolute path to the script (the plugin's install or clone path on that host), never ~ or a relative path. Allow about 15 s on any action that may reconnect wirelessly (avahi discovery waits up to 8 s). Run Command is risk category programs; apply_changes reports risky-action and still applies.

4. Record new actions (the point of this skill)

Whenever an ADB action is worked out in a session (for a deck or not), add it to references/adb-actions.md:

  • the adb-deck.sh subcommand, adding one to the script if the action needs it (keep one subcommand per action);
  • the raw adb command;
  • status: confirmed (ran on a real device: give date, Android version or model, and what you saw) or untested;
  • any trap found on the way.

Commit and push the plugin with the change. No personal IPs, serials or device names in the repo.

Readme

Macro Deck Plugin

Agent skills for turning a phone or tablet into a macropad for host operations with Macro Deck 3: install the host on Linux, connect its built-in MCP server, have the agent build decks from a short spec, and keep every deck in a private git repo you own.

Macro Deck 3 (stable since 2026-10-31) runs on Windows, macOS and Linux. The phone shows the deck (free web client or the paid Companion app) and sends presses; the computer runs the actions. Its MCP server lets an agent create folders, buttons and action flows directly, with dry runs and undo.

Skills

SkillWhat it does
setup-hostInstall Macro Deck 3 from its APT repo, open the ports to the LAN/tailnet, connect the phone; Linux/Wayland caveats
connect-mcpRegister the host's MCP server (/mcp, bearer token) with Claude Code and verify the nine tools
init-decks-repoOnboarding: create a private repo for your decks (decks/<slug>/deck.json specs, snapshots, hosts/)
build-deckBuild or update a deck from a spec: schema discovery via catalog, dry run, apply, verify, record
icon-packsFind icons in installed packs (scripts/find_icon.py), install Store packs, put pack icons on buttons
save-decksSnapshot the live decks into the repo and push
archive-backupCopy an encrypted .macroDeckBackup into the decks repo, index it, check the recovery key is kept
adb-actionsPut ADB actions for a connected Android device on buttons (scripts/adb-deck.sh, wireless reconnect) and keep a catalogue of confirmed actions
restore-decksRecreate decks on a new or rebuilt host from the repo

Order on a new setup: setup-host → connect-mcp → init-decks-repo → build-deck.

Host operations, not keystrokes

Buttons should call something that works without window focus: a local HTTP API (best), or a command. Keystroke buttons need the target window focused and, on Wayland, reach only XWayland apps.

Data

  • Your decks: the private repo you create with init-decks-repo.
  • Plugin config (pointer to that repo): ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/macro-deck/config.json.
  • Tokens and secrets: your password manager; never the repo.

Installation

claude plugins install macro-deck@danielrosehill

License

MIT

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Macro-Deck-Plugin
Author
Daniel Rosehill
Category
Hardware & Maker
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to macro-deck

More Git & Version Control