mxctl-filter

Event filter plugin for mxctl, the Matrix CLI client. Drops events that match configured rules, stopping the pipe chain. Designed to run as the first pipe before notification or processing plugins.

Requirements

• Go 1.21+ (to build)

Installation

go install mxctl-filter@latest
# or build from source:
go build -o mxctl-filter .

Usage

Register as the first pipe in a plugin chain in your mxctl config:

{
  "self_ids":    ["@me:matrix.example.com", "@me:bridge.example.com"],
  "spammer_ids": ["@bot:example.com"],
  "plugins": [
    {
      "name": "notify",
      "exclude_self":     true,
      "exclude_spammers": true,
      "pipes": [
        { "cmd": "mxctl-filter" },
        { "cmd": "mxctl-notify" }
      ]
    }
  ]
}

mxctl invokes mxctl-filter once per event, passing the accumulated event JSON on stdin, --event with the original event, and --config with the pipe config. When exclude_self or exclude_spammers are set on the plugin, mxctl automatically injects the corresponding IDs into the blacklist field of the config before invoking the filter — no manual ID listing in the filter config is needed.

If the event passes all rules, the filter exits 0 and the chain continues. If the event is dropped, it exits 2 — mxctl stops the chain silently (no error logged).

Configuration

Self and spammer exclusion is configured at the plugin level in mxctl config, not in the filter's own config. mxctl injects those IDs into the blacklist automatically.

Field	Type	Description
blacklist	[]string	Drop events from these senders or rooms (Matrix ID).
whitelist	[]string	When non-empty, drop events from any sender or room not in this list (Matrix ID).

Both fields accept a mix of user IDs (@user:server) and room IDs (!room:server) in a single list.

Filtering rules applied in order

1. Blacklist — drops matching senders or rooms (includes any IDs injected by mxctl)
2. Whitelist — drops all senders and rooms not on the list

Constraints

Conflict	Reason
blacklist + whitelist	Mutually exclusive — use one or the other

Exit codes

Code	Meaning
0	Event passes — pipe chain continues
1	Error (config parse failure, invalid stdin)
2	Event filtered — pipe chain stops silently

License

MIT — see LICENSE.