Access

Missing file = { subscriptions: [], publishAllowlist: ["#"], subscribeAllowlist: ["#"], defaultQos: 0 }.

Dispatch on arguments

Parse $ARGUMENTS (space-separated). If empty or unrecognized, show status.

No args — status

1. Read ~/.claude/channels/mqtt/config.json (handle missing file).
2. Show:
   • Subscriptions: count and list of topics with QoS levels
   • Publish allowlist: list of patterns
   • Subscribe allowlist: list of patterns
   • Default QoS level

subscribe add <topic> (optional: --qos 0|1|2)

1. Read ~/.claude/channels/mqtt/config.json (create default if missing).
2. Parse the topic and optional --qos flag (default to defaultQos from config).
3. Add { topic, qos } to subscriptions (dedupe by topic — update QoS if topic already exists).
4. Write back.
5. Confirm. Note that new subscriptions take effect on next broker connect (restart), or Claude can use the subscribe tool to subscribe immediately at runtime.

subscribe rm <topic>

1. Read config, filter subscriptions to exclude entries matching <topic>.
2. Write back. Confirm.

publish-allow add <pattern>

1. Read config (create default if missing).
2. Add <pattern> to publishAllowlist (dedupe).
3. Write back.

publish-allow rm <pattern>

1. Read config, filter publishAllowlist to exclude <pattern>.
2. Write back.
3. Warn if the allowlist is now empty — Claude won't be able to publish anywhere.

subscribe-allow add <pattern>

1. Read config (create default if missing).
2. Add <pattern> to subscribeAllowlist (dedupe).
3. Write back.

subscribe-allow rm <pattern>

1. Read config, filter subscribeAllowlist to exclude <pattern>.
2. Write back.
3. Warn if the allowlist is now empty — the subscribe tool won't work.

qos <0|1|2>

1. Validate the value is 0, 1, or 2.
2. Read config, set defaultQos, write back.
3. Confirm.

Implementation notes

• Always Read the file before Write — the channel server may have been modified externally. Don't clobber.
• Pretty-print the JSON (2-space indent) so it's hand-editable.
• The channels dir might not exist if the server hasn't run yet — handle ENOENT gracefully and create defaults.
• Topic filters are opaque strings. Don't validate MQTT wildcard syntax — the broker will reject invalid filters at subscribe time.