wrongname/mautrix-claude repository overview

⁠mautrix-claude

A Matrix⁠ bridge for Claude AI⁠ built on the mautrix⁠ bridge framework.

Chat with Claude models (Opus, Sonnet, Haiku) through any Matrix client.

⁠Features

• Multi-model support — switch between Claude Opus, Sonnet, and Haiku per room
• Vision API — send images (JPEG, PNG, GIF, WebP) for Claude to analyze
• Per-room configuration — independent system prompt, model, temperature, and max tokens
• Two authentication modes — API key (pay-per-use) or Pro/Max subscription (via Agent SDK sidecar)
• Conversation context — maintains history per room with configurable max age
• Prompt caching — optional cache to reduce API costs on repeated context
• E2E encryption — optional end-to-bridge encryption support

⁠Quick Start

⁠1. Generate config

docker run --rm -v ./data:/data wrongname/mautrix-claude

Edit data/config.yaml — set homeserver.address, homeserver.domain, and bridge.permissions.

⁠2. Generate registration

docker run --rm -v ./data:/data wrongname/mautrix-claude

Register the generated data/registration.yaml with your homeserver.

⁠3. Run

docker run -d --restart unless-stopped \
  -v ./data:/data \
  -e UID=1000 \
  -e GID=1000 \
  wrongname/mautrix-claude

Or with docker compose:

services:
  mautrix-claude:
    image: wrongname/mautrix-claude:latest
    restart: unless-stopped
    volumes:
      - ./data:/data
    environment:
      - UID=1000
      - GID=1000
      - NODE_OPTIONS=--max-old-space-size=2048
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 1G

⁠4. Log in

1. Invite @claudebot:yourdomain.com to a Matrix room
2. Send login
3. Enter your Anthropic API key

⁠Sidecar Mode (Pro/Max)

Use a Claude Pro or Max subscription instead of paying per API call:

1. Authenticate Claude Code on the host: npm install -g @anthropic-ai/claude-code && claude
2. Copy credentials: cp -r ~/.claude/* ./data/.claude/
3. Enable in config:

   network:
     sidecar:
       enabled: true
   

   Copy
4. Restart the container

⁠Commands

⁠Architecture

Matrix Client → Homeserver → mautrix-claude (Go)
                                ├── Anthropic API (API key mode)
                                └── Python Sidecar (Pro/Max mode)
                                      └── Claude Agent SDK → Anthropic

Each Claude model family appears as a separate ghost user in Matrix (e.g. @claude_sonnet:yourdomain.com).

⁠Resource Requirements

• API mode: minimal (lightweight Go binary)
• Sidecar mode: 2-4 GB RAM (Claude Agent SDK bundles Node.js)

⁠Source

https://dev.web.wr0ng.name/wrongname/mautrix-claude⁠