What is Macro Grid

Macro Grid turns a phone or tablet on your local network into a customizable macro deck for your Windows PC, like a hardware macro keypad you design yourself. You lay out buttons, toggles, sliders and knobs on a grid in an editor. The deck shows live values from the PC (CPU, RAM, the time, an OBS stream duration, ...) and presses keys, types text, opens programs, changes the volume and controls other software through plugins.

Beta, AI-generated, at your own risk

Macro Grid is in public beta. All code, design, documentation and artwork, including this site, were created by artificial intelligence (an AI assistant working at the maintainer's direction). Nothing has been reviewed line by line by a human, security-audited or certified for any purpose. Everything is provided "as is", without warranty of any kind. The authors and contributors accept no responsibility or liability of any kind, including for damage, data loss, misuse or security problems. All risk is yours: which software you install, which devices you pair, which plugins you run and which buttons you press. APIs and plugin manifests may still change; the plugin SDK follows semantic versioning (see Compatibility): a minor version only adds to it, a new major version may break plugins.

Architecture

There are three parts, in three repositories, versioned independently.

Part	Repository	What it is
Server and editor	macro-grid	A Windows tray application. It stores profiles, talks to decks over a WebSocket (port 9820), runs actions on the PC and hosts the editor in its own window. It also contains the plugin SDK.
Client	macro-grid-client	The Android app that draws the deck and reports touches. Any browser can also act as a deck at http://<PC address>:9820/deck/.
Plugins	macro-grid-plugin	The official plugins and this documentation.

┌───────────── Windows PC ───────────────────────────────┐
│  Macro Grid server (tray app)                          │
│   ├─ port 9820: /ws  WebSocket for phones and decks    │
│   │             /api editor API (this computer only)   │
│   ├─ the editor (a WebView2 window)                    │
│   ├─ core: profiles, actions, variables, plugins       │
│   └─ Windows: key input, audio, system metrics         │
└───────────────▲────────────────────────────────────────┘
                │ WebSocket, JSON, local network only
     phone / tablet app  ·  any browser at /deck/

Plugins run inside the server. They add four kinds of things:

• Actions: things a widget can do when it is pressed (switch an OBS scene, bump a counter).
• Variables: live values a widget can show in its text ({obs.stream.duration}) or use in rules that change its color or icon.
• Settings pages, status bar items: a form in the Plugins window and a colored entry in the editor's status bar.
• Icon packs: sets of icons for the editor's icon picker.

A plugin cannot draw its own widget or add a widget type yet.

Who can write which kind of plugin

	Official plugin (C#)	Plugin by anyone else (JavaScript)
Trust	Full trust, inside the server process. Signed by the maintainer, and the server checks the signature every time it loads.	Sandboxed, only a small host object and approved permissions
Good for	The plugins in this repository	Small scripts (poll a local HTTP API, publish a variable, add an action)
Needs a build	Yes	No

Third-party plugins are JavaScript. A C# plugin runs with full access to the PC and Macro Grid cannot limit it, so the server loads a C# plugin only when it is one of the official, signed plugins. A JavaScript plugin shows the permissions it asks for and only runs after you approve them. Macro Grid does not review plugins from other authors: install only ones you trust.

Where to go next

• New to Macro Grid? Getting started installs the server and pairs a phone.
• Want to write a plugin? Start with Plugin basics, then Tutorial 1.