configure

Configure Matrix Channel

Set up the Matrix bot credentials for the channel plugin.

Usage

The user provides: /matrix:configure <homeserver_url> <access_token>

Parse the arguments from "$ARGUMENTS". Extract the homeserver URL (first argument) and access token (second argument).

If arguments are missing, ask the user to provide them:

• homeserver_url: The Matrix homeserver URL (e.g., https://matrix.example.com)
• access_token: A Matrix access token for the bot account

Validation

The homeserver URL MUST include the protocol scheme (https:// or http://). If the user provides a URL without a scheme (e.g., matrix.example.com), automatically prepend https://. Always strip any trailing slashes.

Steps

1. Create the directory ~/.claude/channels/matrix/ if it doesn't exist:

   mkdir -p ~/.claude/channels/matrix
   

2. Validate the homeserver URL has a protocol scheme. If it does not start with https:// or http://, prepend https://.

3. Ask the user for their bot's Matrix user ID (e.g., @claude-bot:example.com)

4. Write the .env file at ~/.claude/channels/matrix/.env:

   MATRIX_HOMESERVER_URL=<homeserver_url>
   MATRIX_ACCESS_TOKEN=<access_token>
   MATRIX_BOT_USER_ID=<bot_user_id>
   

5. Confirm the configuration was saved.

6. Remind the user to set up their allowlist with /matrix:access add <user_id> if they haven't already.

Per-project room filtering

To restrict a Claude Code project to specific Matrix rooms, set MATRIX_ROOM_IDS in the project's .claude/settings.local.json or in the .env file:

MATRIX_ROOM_IDS=!roomA:example.com,!roomB:example.com

• Comma-separated list of Matrix room IDs.
• When set, only messages from those rooms are forwarded to Claude, and the bot will only auto-join those rooms on invite.
• When unset, all rooms are forwarded (default behavior).