obs-tools/CLAUDE.md

CLAUDE.md

Style

• Keep everything short: replies, explanations, comments, docs.
• Use simple English: short sentences, common words.
• Avoid em dashes (—). Do not just swap them for "-" either. Rewrite the sentence instead, for example with a comma, a colon, brackets or two sentences.

Commits

• English only.
• Conventional Commits prefix: feat:, fix:, chore:, docs:, refactor:, ci:, build:, test:.
• Subject as short as possible. Imperative, lowercase, no trailing period.
• Body only when something genuinely cannot be inferred from the diff.
• Never add Co-Authored-By, "Generated with" or any other AI attribution to commits or PR descriptions.
• Do not commit or push before I have checked the changes locally and said they are fine. Then commit and push. Several attempts at the same thing make one commit, and attempts that did not work make none. Different things done in one session get a commit each. This also goes for releases and tags.

Project

• The plugin is plain JavaScript (ES modules) for Node.js 22+, without dependencies. Keep it that way: OpenDeck runs it with the system Node, and there is no build step.
• Plugin ID is de.felitendo.obs-tools (folder de.felitendo.obs-tools.sdPlugin), like the Feishin plugin. Do not change it again: OpenDeck keys profiles and settings by it.
• manifest.json and the icons in images/ are generated. Change scripts/manifest.mjs or the glyphs in plugin/lib/icons.js, then run make manifest or make icons. make icons first measures every glyph (scripts/fit-glyphs.mjs, needs ImageMagick), so all icons end up the same optical size and optically centered (halfway between the middle of the box and the center of mass, so a play triangle does not look too far left). The action order in scripts/manifest.mjs is the order in OpenDeck: most used first.
• Settings pages come from pi/schemas.js. A new setting needs a default in the action class and a field in the schema. The status line is on top. Its "Change" button opens the connection settings right below it, and they open by themselves while OBS cannot be reached. The settings of the key follow in sections (section in pi/schemas.js): what the key is about, Controls, On the key, and closed sections for the rest. Use the own dropdown(), checkbox() and number stepper in pi/pi.js, never native <select> or checkboxes: OpenDeck's WebKitGTK draws those in the GTK style.
• An action that can do more than one thing lists it in static ops (the press choice is in the setting pressKey), and its schema uses gestures(). Press, hold and double press then offer the same choices, and the base class does the key handling.
• Settings a key cannot work without go in static required, so the key shows the setup image (gray glyph, yellow dot) until they are set. Errors an action throws show up on its settings page: write them as short English sentences and add the German text.
• Everything a user can read comes in English and German. Write the English text in the code and wrap it in t() (from plugin/lib/i18n.js), then add the German text there. Action names and tooltips for the OpenDeck list are in scripts/manifest.mjs (it writes de.json). Messages the plugin sends to a settings page stay English, the page translates them with translateMessage(). make check fails when a German text is missing.
• Keys look like the other FeloDeck plugins too: no background, bold white glyph in the middle, gray when off. Dials with their own touch strip layout use layouts/*.json.
• Test in the real apps. First check if a real Stream Deck is plugged in (lsusb | grep -i 0fd9, Elgato's USB vendor ID). If one is, test on it, but only in new profiles of its own, with a name that is not taken yet (for example "OBS Tools Test"). Never change or delete the profiles that are already on it, they are in use. Note which profile was selected before (~/.config/opendeck/profiles/<device>.json) and select it again when done. make-profile.mjs only writes profiles for the virtual deck.
• Without a real Stream Deck, use the virtual deck: make install install-virtual-deck, restart OpenDeck, put actions on keys with tools/virtual-deck/make-profile.mjs (OpenDeck must be stopped), then run the matching test/e2e/run*.mjs.
• make check runs the unit tests. OBS that is busy encoding (a weak VM) can make the end-to-end tests flaky, run them again before hunting a bug.

Releases

1. Read git log <last tag>..HEAD and pick the version: only fixes → patch, something new → minor, something that breaks or needs the user to act → major.
2. Bump VERSION, run make manifest and add the entry at the top of CHANGELOG.md, in one commit (chore: 1.4.0).
3. Push, then push the tag: git tag v1.4.0 && git push origin main v1.4.0.

A minor or major release starts with a welcome sentence and has a ### Highlights list. A patch release is just a sentence or two. Write for users: what they notice, not how the code does it.

README

• The virtual deck is a test tool. The README does not mention it.
• New UI (a key, a settings page) gets a screenshot in the README, next to the text about it. A real screenshot of it running, in English.
• When a screen changes, take its screenshot again. The README never shows an old one.