Matterbridge security plugin

This plugin allows you to create a security system.

• Five preconfigured modes: Home, Away, Night, Vacation, Off.
• Five preconfigured setters: Home, Away, Night, Vacation, Off.
• Four preconfigured triggers: Home, Away, Night, 24h.
• Five preconfigured alerts: Home, Away, Night, 24h, Master.
• Persistent history of mode changes, accepted triggers, startups and shutdowns, with timestamps and a configurable event limit (default: 100).
• Color-coded frontend event table with local date and time display.

The plugin requires matterbridge v.3.11.0.

Each mode is exclusive: the other will revert their state.

Mode vacation works exactly like mode away. Is useful to create on the controller some automations that turn on and off internal lights when you are on vacation.

Setters will set the corresponding mode and will revert immediately their state.

Is usefull when the controller doesn't allow to lock unlock doors from presence automations. They are enabled by the useSetters config.

Triggers are momentary switches you can use in your controller automations to start an alarm.

Triggers will trigger the corresponding alarm and will revert immediately their state.

On your controller you need to create an automation that trigger each trigger.

Alerts are the alarm states exposed by the plugin; they stay active for the configured alertTimeout and then reset.

The platform's events array contains the latest security events, oldest first. Set eventsNumber in the plugin configuration to an integer from 10 to 1000 to control how many events are retained (default: 100). Existing configurations without this option default to 100 on startup. History is saved in plugin storage under SecurityEvents and restored on startup.

The plugin frontend displays all retained events, oldest first, with color-coded event types and dates formatted for your browser's locale and timezone. Use Refresh to load the latest events. Timestamps remain in ISO format in storage and in the plugin's GET /plugins/matterbridge-security/api/events response.

Trigger events are displayed as Alarm in the frontend (for example, Alarm Away). Stored events and the API retain the trigger type and original trigger names.

Each entry contains datetime (an ISO 8601 UTC timestamp), event (the mode or trigger name, Startup, or Shutdown), and type (mode, trigger, startup, or shutdown).

• Mode events are recorded only when the mode changes, including changes to Off. Restoring the mode on startup does not add a mode event.
• Trigger events are recorded only when a trigger activates alerts in the current mode. Ignored triggers and automatic alert resets do not add events.
• Startup events are recorded after initialization completes. Shutdown events are saved before plugin storage closes.

{ "datetime": "2026-10-17T17:38:25.632Z", "event": "Mode Away", "type": "mode" }

See also the Style Guide for JSDoc, naming, and logging conventions used in this repository.

Note: This repository uses a new toolchain. It replaces the traditional TypeScript / ESLint / Prettier / Jest stack with a faster and lighter setup.

• No typescript 6.x package — replaced by TypeScript Native 7.x.
• No ESLint, no Prettier — replaced by the oxc stack: oxlint for linting and oxfmt for formatting.
• No Jest — replaced by Vitest, which is much faster and natively supports ESM without extra configuration.
• Far fewer development dependencies — the number of installed packages drops from ~600 to ~75. A clean install is much faster.
• Much faster linting and formatting — oxlint and oxfmt run in a fraction of the time required by the ESLint / Prettier pipeline.
• Much faster builds — tsgo compiles the project in a fraction of the time required by the standard tsc build.
• Editor support — use the VS Code extensions for tsgo and oxc to get the same experience in the editor.

All coding agents read the same guidance. AGENTS.md and .agents/ are the single source of truth; everything under .github/, .claude/, .codex/ and .antigravity/ are pointers and mirrors. Edit .agents/ (or AGENTS.md), never the copies. See .agents/README.md for the full layout.

Content lives only in .agents/. The per-agent folders exist because each tool discovers rules and skills from its own hardcoded location, so they hold stubs that point back here — except where the tool reads .agents/ natively.

Codex reads the shared rules and skills from .agents/ directly; the skill is invoked as $verify-agent-context.

The shared rules under .agents/rules/ apply on demand for the relevant tasks, and .agents/skills/ is discovered automatically as /verify-agent-context.

Refer to the Matterbridge Development guide for other guidelines.