OMP Studio (omps)

A modern script editor for Grenton home-automation projects.

OMP Studio gives Grenton installers and integrators a VS Code-like editor for the Lua scripts inside a .omp project file — with firmware-accurate autocompletion, real-time validation of Grenton-specific semantics (CLU->Object->Feature chains, cross-CLU quirks, read-only features), project-wide search, and automatic backups. It replaces the built-in script editor of Object Manager for writing and reviewing code; Object Manager remains the tool that deploys to the CLUs over LAN.

Quickstart

Run the CLI next to your project file (no account, no login):

npx @omp-studio/omps YourProject.omp

Windows, no Node.js installed?

Paste this once into PowerShell (Win+R → type powershell → Enter):

irm https://omp-studio.coderai.dev/install.ps1 | iex

It installs a private Node.js runtime and the agent into your user folder (%LOCALAPPDATA%\omp-studio) — no admin rights, nothing system-wide. From then on:

• Shift+right-click your .omp file → “Edit in OMP Studio” (plain right-click works too, on Windows 11 under “Show more options”; double-click still opens Object Manager, as before), or
• run omps YourProject.omp in any terminal — no npx needed.

Re-run the same line anytime to update. Uninstall with omps uninstall-windows (then delete the %LOCALAPPDATA%\omp-studio folder).

macOS: "Open With" in Finder (optional)

For an integration that updates itself, install globally first, then set it up:

npm i -g @omp-studio/omps && omps setup-macos

Builds a small opener app in ~/Applications, so right-click on a .omp file → Open With → OMP Studio launches the agent in Terminal (you can make it the double-click default via Get Info → Change All). On first use macOS asks once to allow controlling Terminal. Remove with omps uninstall-macos; after reinstalling/moving Node or the package, re-run setup-macos.

You can also just try it via npx @omp-studio/omps setup-macos — but a droplet built that way is pinned to the npx cache copy and won't auto-update, so prefer the global install above for a permanent setup.

That's it. The CLI:

1. unpacks the .omp into a local working copy (a git repository, for history),
2. builds a knowledge index from your project and your own Object Manager installation's device-interfaces catalog — so completion and validation match exactly the firmware versions you actually run,
3. opens the hosted editor at https://omp-studio.coderai.dev in your browser, already connected to your project.

Keep the terminal running while you work. As long as the process is open, edits you make in the browser flow straight back into the local .omp (a timestamped .bak of the original is kept, and every edit is versioned in a local git history), and changes you make in Object Manager flow up to the editor. Press Ctrl-C to stop — your .omp keeps the last synced state. When you're done, open the project in Object Manager and deploy as usual.

Useful flags:

npx @omp-studio/omps YourProject.omp --no-browser   # print the editor URL instead of opening a browser
npx @omp-studio/omps YourProject.omp --resync       # force a full resync: the local .omp overwrites the cloud state
npx @omp-studio/omps YourProject.omp --verbose      # print the live sync activity log (quiet by default)
npx @omp-studio/omps YourProject.omp --ai           # enable AI help (choose a local agent); --no-ai turns it off

AI help (optional, local agent)

If you have a coding agent installed — claude (Claude Code), codex, opencode, or pi — the editor's AI box can drive it to write and fix Grenton Lua scripts for you, right on your machine. It runs in your project's working copy using your own agent account/credits; nothing about your code or keys leaves your computer beyond the edits you already sync.

The first time you open a project in a terminal, omps looks for agents on your PATH, checks that they actually start, and asks which one to use (if any); your choice is remembered across projects. To change it later:

omps ai                 # show what's installed and the current choice, then pick
omps ai codex           # set a specific agent (and health-check it)
omps ai off             # disable AI help
omps ai reset           # forget the choice, so the next open asks again

Per run you can also pass --ai (re-open the chooser), --ai=<agent> (force one), or --no-ai (skip it). While an AI run is in flight the editor is read-only until it finishes.

Scripting from the command line (omps script / omps event)

Structural changes the cloud editor can't make on its own — because they touch system.xml, which never leaves your machine — are exposed as CLI commands. They act on the running session: keep an omps terminal open on the project (omps open YourProject.omp), then run these from anywhere inside the project (or point them at the .omp explicitly). They're the same operations the editor and a local AI agent drive, so a --ai agent uses exactly these verbs. With no live session they fail fast (exit 1, no-session, and a hint to run omps open).

omps script — the script registry (.lua files + their system.xml entries):

omps script ls   [--clu CLU01]                        # list scripts per CLU, with params
omps script add    --clu CLU01 --name sFoo            # create an empty script
omps script rename --clu CLU01 --name sFoo --new-name sBar
omps script rm     --clu CLU01 --name sFoo            # delete-to-trash (kept until OM empties trash)

rename/rm refuse (has-references) while anything still calls the script — an OM event binding or another script — and refuse visual scripts, which must be managed in Object Manager.

omps event — the command lists wired onto an object's (or CLU's) events:

omps event ls  [--clu CLU01] [--owner Przycisk] [--all]   # --all folds in unbound catalog events too
omps event add --clu CLU01 --owner Przycisk --event OnClick --command 'CLU01->sFoo(1)'
omps event set --clu CLU01 --owner Przycisk --event OnHold  --index 0 --command 'CLU01->sBar()'
omps event rm  --clu CLU01 --owner Przycisk --event OnHold  --index 1

set/rm take a 0-based --index into the current command list. To edit safely against a list that may have moved under you, add --expect '<current text>' (compare-and-swap): the op only lands if commands[index] still equals that text, otherwise it fails with conflict. A bare --expect with no value is rejected rather than silently disabling the check.

Every verb accepts --json for scripting: success prints {"ok":true,…} (an ls adds scripts/events), and every failure — bad arguments, no session, a rejected op — prints {"ok":false,"code":…,"error":…}. The exit code is 0 on success, 1 on any failure.

Your project stays yours

The .omp file on your disk is always the source of truth — it never leaves your machine.

• Only the editable project content syncs to the cloud session: your Lua scripts, the rooms layout (home.json), visual-script node data, and a derived project index (object names, features, methods — the data the editor needs for completion and validation).
• system.xml, properties.xml (which contains the project cipher key), virtual-device files and diagnostics are never uploaded — they never cross the API boundary.
• No account or login is required. The CLI provisions an anonymous cloud session with capability tokens scoped to that project.

What the editor gives you

Language intelligence

• Firmware-accurate autocompletion, derived per session from your project and your Object Manager install — never from a generic bundled catalog. Complete CLU and object names, features, methods with full signatures, events, user features, and scripts (inserted in their callable CLU->Script(...) form). Enum-typed features and parameters complete with their numeric values and human-readable labels (e.g. 1 — ON). SYSTEM-style builtins complete with dot syntax, exactly as the firmware expects.
• Hover documentation in English or Polish, straight from the firmware catalog hints: feature types, units, read-only/read-write access, defaults, allowed enum values, method signatures, user-feature metadata.
• Signature help while typing call arguments — for module methods, builtins, and your own scripts, with per-parameter enum documentation.
• Full grenton-lua syntax highlighting, including -> chains, plus a subtle whole-block highlight when the cursor sits on if/for/function/end.

Validation — catch bugs before they reach a wall switch

Every keystroke is linted client-side (with a short debounce), combining a live Lua syntax check that understands Grenton's -> chains with a Grenton-specific rule set:

• Typos in names — referencing a CLU or object that doesn't exist in this project, or a feature/method that doesn't exist on the resolved target's firmware interface. In Object Manager these fail only at runtime; here they're red before you save.
• Writes to read-only features — assigning to a feature the firmware declares set="false".
• Undefined user features — using CLU->vSomething when that user feature isn't defined on that CLU (with a hint if it exists on a different CLU).
• The cross-CLU local-variable trap — a Grenton quirk where the right-hand side of a write to another CLU, and the arguments of a call to another CLU's script or method, are evaluated on that CLU. Literals and -> references work (OtherCLU->Obj->Value = 1, OtherCLU->vX = ThisCLU->vY, OtherCLU->sFoo(ThisCLU->vY)), but a script-local variable fails silently: in local v = 1; OtherCLU->Obj->Value = v or OtherCLU->sFoo(v), the variable v doesn't exist on OtherCLU, so the value never arrives. This is one of the nastiest bugs to debug on site; the editor flags every occurrence and suggests passing the value through a user feature (ThisCLU->vTmp = v, then OtherCLU->Obj->Value = ThisCLU->vTmp).
• Call-argument checks — too many arguments, enum arguments outside the allowed value set, non-numeric strings passed where the firmware expects a number. Coercion-aware: omitted arguments are legal (Grenton applies defaults), so you only see real problems.
• Wrong separator — using Lua's . or : on a Grenton entity where -> is required (or vice versa for builtins), with the corrected form in the message.
• Semicolons — Grenton's Lua parser rejects ; entirely (end of line, statement separator, even in table constructors). Ordinary Lua habits compile everywhere else and then fail on the CLU; here every semicolon is red immediately.
• Arrows in comments — never put -> in a Lua comment, including after --. Object Manager's Grenton preprocessor sees it as a command/reference before Lua removes the comment; rephrase it (for example, use “to” instead of ->).
• Line comments after Grenton assignments — do not append -- comment to TARGET->Feature = value or CLU->Object->Feature = value. The preprocessor wraps the right-hand side and appends a closing parenthesis that the line comment hides, producing invalid generated Lua. Put the comment on the line above; inline comments after ordinary Lua statements and complete Grenton calls remain valid.

Problems, everywhere — not just the open tab

• The Problems panel lints every script in the project, including files you never opened, so a rename that breaks a script three CLUs away shows up immediately.
• Problem lines get tinted line numbers in the editor gutter, and every script in the explorer carries a per-file problem badge with its error/warning count.

Navigation & search

• Go to definition / Cmd-click: any script referenced in a -> chain jumps to its source; script references are underlined, clickable links.
• Project-wide search across all scripts.
• Quick-open (Cmd/Ctrl+P) fuzzy file picker.
• "Called from" at a glance: every script in the explorer carries a badge counting where it is invoked from — hover to see the Object Manager event wirings (CLU->Object->OnEvent) and the calling scripts with line numbers. Scripts nothing triggers, and scripts that can't affect anything, are dimmed and iconed.
• 3D relationship map: an animated, navigable map of your whole installation's wiring — objects trigger scripts, scripts call scripts, scripts operate on objects — with each CLU settling into its own colored "galaxy". Click a node to inspect its connections, double-click to fly to it, and open any script's code straight from its panel.

Project browser

A read-only Objects view of the whole installation: CLUs with their modules and objects, each object's features, methods and events (from the firmware catalog), user features with type/default/persistence, and scripts with their parameters — filterable, and one click from any script to its code.

Editor comfort

• Tabbed Monaco editor (the same engine as VS Code), dark and light themes.
• Workspace persistence: open tabs, the active tab and even unsaved edits survive a page reload.
• UI in English and Polish.

Safety & history

Editing an installer's project file demands paranoia, and the CLI provides it:

• Automatic backups: before the session's first write, the .omp is copied to YourProject.omp.bak-<timestamp> — and again any time an external change (e.g. an Object Manager save) is about to be overwritten. In-session states aren't .bak-spammed: they live in the git history below.

• Git-based local history: the working copy is a real git repository. Inspect and roll back from the terminal:

  npx @omp-studio/omps history YourProject.omp          # list versions
  npx @omp-studio/omps diff    YourProject.omp [a [b]]  # compare versions
  npx @omp-studio/omps restore YourProject.omp <commit> # roll back (with backup)

• Drift detection: the CLI watches the .omp and the working copy (plus a 30-second hash heartbeat). If Object Manager saves the project while your session is open, OMP Studio detects it, re-derives the project with a human-readable change summary, and resolves conflicts per file instead of clobbering anything.

• Guarded repack: the .omp is never blindly overwritten — if the file on disk no longer matches what the session last saw, the save stops and reconciles first. Every save replaces the file atomically, so nothing reading it mid-save (Object Manager, a sync service like OneDrive) can ever catch a half-written archive.

• Unsaved work survives: edits that never made it into the .omp — say the machine went down mid-session — are recognized on the next open and re-applied on top instead of being wiped by the fresh unpack.

• One session per project: a lock next to the .omp (it also works across machines on a synced folder) prevents two sessions from fighting over one file. Running omps a second time on the same machine reconnects you to the running session instead of failing; from another machine you'll be asked to close the running session first.

• System files are off limits: system.xml, properties.xml, virtual-device files and diagnostics are always packed from the authoritative .omp, never from the working copy — nothing that edits files on disk (you, a script, an AI tool) can corrupt the parts of the project only Object Manager understands.

• The CLI's small status endpoint (used to reconnect a second omps run to an already-running session) binds to loopback only, with Host/Origin validation; unpacking is zip-slip-guarded.

How it fits with Object Manager

OMP Studio is a companion, not a replacement. Object Manager still owns configuration and deployment: it talks to the CLUs on the LAN, uploads the configuration and runs the project. OMP Studio makes the scripting part of the job fast and safe — edit with real language tooling, then switch to Object Manager to send the project to the installation. Because all completion and validation data comes from your own OM installation's device-interfaces catalog, what the editor accepts is what your firmware accepts.

Staying up to date

omps checks npm for a newer version when it starts (at most once an hour, skipped silently when offline) and asks before updating itself in place — the update matches how you installed it (the Windows one-command install, or npm -g). Answering "no" snoozes that version for a week. Set OMPS_NO_UPDATE_CHECK=1 to turn the check off entirely.

Requirements

• An internet connection — OMP Studio is an online tool: the editor runs in your browser against the hosted service (your .omp, system.xml and cipher key still never leave your machine — see above)
• Node.js ≥ 20
• A Grenton .omp project file
• An Object Manager installation on the same machine (for the firmware catalog; --om-path overrides auto-detection)
• git — on Windows, if it's missing, omps automatically downloads a checksum-verified portable copy into its own folder (one time, no admin rights); on macOS/Linux install it via your usual tools