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:
   ```bash
   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).