AI board operator in the terminal — talk to your grandMA3 console in plain English. Optimized for MA3 version 2.3.2.0
Store data · Write plugins · Analyze your showfile.
Setup · Commands · Models · How it works · Accuracy · Safety
BoardOp is a tireless assistant programmer for grandMA3. You type plain English — "turn group 69 on, make them orange" — and it turns that into real MA3 commands or a full Lua plugin and deploys it straight to the console.
op@claude:~$ turn group 69 on, make them orange
# → builds the cues + sequence and deploys them to the console
op@claude:~$ @gemini now make them blue
op@gemini:~$ @claude actually revert that
# ↑ switch AI engines mid-session — the conversation carries over
It's not just a command generator. Ask it what a sequence does, what's patched in your show, or how you'd build something before committing — it reads your actual showfile and answers in plain English. As useful for understanding a show (or learning the console) as it is for changing one.
- 🗣️ Plain English → real MA3. Sequences, cues, MAtricks, presets, executors — described, not hand-typed in exact syntax.
- 👁️ It sees your show. A live snapshot of your showfile — every pool, the rig, what's playing, even the programmer — so it works with your real names and IDs.
- 🔁 Self-healing. When the console rejects a plugin, the error loops back to the AI and it fixes its own code, within safe bounds.
- 🪟 Plugins into panels.
@polishturns a working plugin into a resident GUI panel — on-screen buttons and fields, imported natively into the plugin pool. - 🧠 Dual-AI, one memory. Claude and Gemini, swappable mid-session with full context handover.
- 📚 Grounded in console truth. Built on a verified object model harvested from the console itself, so it doesn't invent syntax.
- 🛡️ You approve everything. Destructive commands and every generated plugin pause
for your
y/nbefore anything touches the console.
You need a Windows PC running grandMA3 onPC (v2.x), Python 3.10+, and your own API key for Anthropic (Claude) and/or Google (Gemini). Your conversations go directly to your provider and nowhere else.
💡 Want to try it for free? Google AI Studio offers a free tier for Gemini models. Get a key at aistudio.google.com/apikey, set
GEMINI_API_KEYandDEFAULT_AI = "gemini", and you can run BoardOp without paying for API usage — the free tier is rate-limited, so expect to wait between requests on a busy session. Anthropic has no free tier; a Claude key is pay-as-you-go.
1 — Get the code and install dependencies
Clone or download this repo, then double-click setup.bat. It creates a private
.venv and installs the dependencies into it, leaving any other Python on your machine
untouched.
2 — Add your API key
Run run_server.bat. The first launch creates a config.py for you and stops. Open
it and set:
| Setting | Value |
|---|---|
ANTHROPIC_API_KEY and/or GEMINI_API_KEY |
your own key(s) |
MA3_PLUGIN_DIR |
your grandMA3 plugins folder |
3 — Turn on OSC in grandMA3 (once per showfile)
In Menu → In & Out → OSC, configure an interface to match:
| Setting | Value |
|---|---|
| Input Port (MA receives) | 8000 |
| Output Port (MA sends) | 8001 |
| Destination IP | 127.0.0.1 |
| Enabled | Yes |
Then make sure SendOSC row 3 exists and is enabled — that's the row BoardOp reads
answers back on. These must match the ports in your config.py; change one, change both.
4 — Run it
Launch run_server.bat again and pick an engine. BoardOp installs its own two helper
plugins (QUERYAI and GETCONTEXTAI) into your showfile automatically — there is
nothing to import by hand. If startup reports a problem, run @doctor for a green/red
health check of the OSC round-trip, both plugins, and your config.
📖 Full setup guide, first-session walkthrough, and troubleshooting →
Everything else is just plain English. Type @help in the session for the full list.
| Command | What it does |
|---|---|
@claude / @gemini |
Switch engine mid-session, keeping the full conversation. Can append a prompt: @claude make a chase |
@polish [Name] |
Turn the last plugin into a resident GUI panel, or @polish Name = describe one |
@save <name> |
Export the last Lua plugin as a grandMA3-importable XML file |
@update ... |
Add your own rules and constraints, so BoardOp works your way |
@context |
Force a showfile refresh (automatic after every acting turn) |
@doctor |
Health check: OSC round-trip, helper plugins, luacheck, config |
@inject |
Reinstall or refresh the console helper plugins |
@query <kind> ... |
Read the console directly, e.g. @query exists Sequence 1 |
@help |
Show the in-session help |
exit / quit |
Close the bridge (session history is wiped) |
BoardOp runs whatever model your API key can reach — the engine choice (Claude or Gemini) and
the model within it are separate settings. Set them in config.py:
CLAUDE_MODEL = "claude-sonnet-5" # the default
GEMINI_MODEL = "gemini-2.5-flash" # the defaultRestart BoardOp after editing; the model is read at startup. @doctor will tell you if a key
or model looks wrong.
Claude — pick by how hard the work is.
| Model | Good for |
|---|---|
claude-sonnet-5 |
The default. Best balance of speed, cost, and accuracy for everyday programming. |
claude-opus-5 |
The hardest jobs — intricate plugins, tricky multi-step show logic. Slower and more expensive. |
claude-haiku-4-5 |
Cheapest and fastest. Fine for simple commands and questions; weaker on plugin authoring. |
Gemini — pick by budget.
| Model | Good for |
|---|---|
gemini-2.5-flash |
The default. Fast, and available on Google AI Studio's free tier. |
gemini-2.5-pro |
Stronger reasoning for complex plugins, at a higher cost. |
Things worth knowing before you switch
- Use the exact model ID. A typo or an invented name fails with a "model not found" error rather than falling back to something sensible. Anthropic publishes its IDs at platform.claude.com and Google at ai.google.dev.
- Your key has to have access. Model availability depends on your account and billing tier, not on BoardOp. If a model 404s, that's the provider's answer, not a bug here.
- Both engines stay available.
CLAUDE_MODELandGEMINI_MODELare independent, so you can keep a cheap Gemini model for quick questions and switch to a stronger Claude model mid-session with@claudewhen you hit something hard. The conversation carries over. - Newer Claude models think before answering, and that reasoning shares the
CLAUDE_MAX_TOKENSbudget with the visible answer. If a long Lua plugin comes back cut off mid-script, raiseCLAUDE_MAX_TOKENSrather than retrying. TEMPERATUREdoesn't apply to current Claude models. Anthropic removed the setting on its newest models, so BoardOp only sends it where it's accepted. It still affects Gemini.- Cost scales with your showfile. Every turn includes a snapshot of your show, so a large
showfile costs more per request than a small one — the
[tokens]footer after each turn shows what you actually spent.
You (terminal)
│ natural language
▼
BoardOp ──► AI engine (Claude / Gemini)
│ │
│ └─► MA3 commands or a generated Lua plugin
│ OSC (localhost)
▼
grandMA3 ──► errors feed back ──► the AI self-corrects
BoardOp runs next to grandMA3 onPC on one machine and talks to it over localhost. To drive a real desk, that onPC joins your console's session and MA's own session sync carries the changes across — hardware-verified on a real grandMA3 console.
The hard problem with an LLM and a lighting console isn't conversation — it's that a
model will confidently invent MA3 syntax, reach for the removed grandMA2 gma. API, or
fire a command that is accepted but does the wrong thing. BoardOp attacks that on three
fronts.
Grounded in a harvested object model, not in guesses. The AI is given a verified map of the console's own object model, captured by walking the live console rather than scraped from prose:
| Corpus | Contents | Captured from | Reached by |
|---|---|---|---|
| Object model | 675 classes, 30,647 properties | the console's object tree (MA3 2.3.2.0) | digest in every request + class_schema query |
| Lua API | 156 functions, with signatures | the official 2.3 function reference | lua_api query |
| Enum values | 617 collections, 5,290 members | the console's Enums global |
shipped corpus, not yet wired in |
A compact digest of the object model rides in every request, and the full corpora are read on demand rather than held in the prompt. Property names therefore come from the console, not from the model's memory.
It reads before it acts. Before doing something that depends on live state, the AI queries the console directly — does this object exist, what's selected, what's running, what is this property set to, what can this fixture type actually do.
It checks its own work. The dangerous case is a command the console accepts that silently doesn't land. After acting, BoardOp reads the result back off the console and compares it against what was intended — whether a stored target actually holds data, whether a written property really took the value it was given. A mismatch is surfaced to you and fed back to the AI instead of passing as success.
Behind all of this sits a layered ruleset of console-verified command syntax — corrections
proven against a real console, not inferred. It's the part of BoardOp that improves
fastest, and report.bat bundles a session into a feedback report you can send back.
None of this makes the AI infallible. It makes it checkable — which is why you still approve everything that matters.
Every action passes through gates before it reaches the console:
- Destructive commands (
Delete,DeleteShow,Purge,Knockout) pause fory/n. - Every generated plugin is shown for review before it deploys.
- Mixed responses are all-or-nothing: if a turn has commands and a plugin, the commands are held until you approve the plugin — reject it and nothing fires.
- Auto-heal is bounded, and console errors are surfaced rather than swallowed.
These are guardrails, not guarantees. BoardOp is built for programming and pre-production, not live show operation — always work on onPC first, keep a hand on the console, and never point it at a show you can't afford to interrupt.
BoardOp is in beta. It's feature-complete and drives a real console, but it's a power
tool, not a polished product. Bug reports and session feedback (report.bat) are the most
useful thing you can send.
Licensed under FSL-1.1-ALv2 — free to use, modify, and
redistribute for any purpose (including professional show programming), except
offering it as a competing product. Each release converts to plain Apache 2.0 after
two years. The console-side plugins in ma3_plugins/ are MIT-licensed, so
showfiles that include them can be shared freely.
"grandMA3" is a trademark of MA Lighting Technology GmbH. BoardOp is an independent, unofficial project, not affiliated with or endorsed by MA Lighting.