configure

name	configure
description	Configure Matrix channel credentials (homeserver URL, access token, bot user ID). Use when the user wants to set up or update their Matrix connection.

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).