claude-matrix-bot

A Matrix bot that gives you a Claude Code agent accessible from any Matrix client — including WhatsApp, via the mautrix bridge. Built for phone-based server administration without needing SSH.

What it does

Send natural-language commands to a private Matrix room. The bot forwards them to the Anthropic API with tool use, executes the tools on the server, and replies with the results. It's Claude Code, but in a chat window.

Tools available to Claude

Tool	What it does
bash(command, timeout)	Run any shell command
read_file(path)	Read a file
write_file(path, content)	Write a file
edit_file(path, old, new)	Replace a string in a file

Bot commands

Command	Effect
!help	List all commands
!reset	Clear conversation history
!trim [n]	Keep last n turns (default 5)
!model sonnet|opus	Switch Claude model
!cost	Token usage + estimated cost
!history	Turn count + last 3 message previews
!status	Model, uptime, history, memory file count
!reload	Re-read memory files from disk
!system	Show system prompt size and loaded files
!debug	Toggle tool call visibility

Setup

Prerequisites

• A Matrix homeserver (Synapse, Conduit, etc.)
• A dedicated Matrix bot account
• Python 3.10+
• An Anthropic API key

Install

git clone https://git.pooperpalace.ch/mikd/claude-matrix-bot
cd claude-matrix-bot
pip install anthropic requests
cp .env.example .env
# Edit .env with your values

Configuration

Variable	Description
MATRIX_BOT_TOKEN	Bot account access token
CLAUDE_BOT_ROOM_ID	Room ID the bot listens in
ANTHROPIC_API_KEY	Your Anthropic API key
ALLOWED_SENDER	Matrix user ID allowed to use the bot

Paths can be overridden via environment variables:

Variable	Default
CLAUDE_ENV_FILE	.env next to the script
CLAUDE_STATE_FILE	claude_bot_state.json next to the script
CLAUDE_MEMORY_DIR	memory/ next to the script

Run as a systemd user service

cp claude-bot.service ~/.config/systemd/user/
# Edit the service file to set your paths and env vars
systemctl --user daemon-reload
systemctl --user enable --now claude-bot
journalctl --user -u claude-bot -f

Memory files

Drop .md files into the memory/ directory (or wherever CLAUDE_MEMORY_DIR points). They're loaded into the system prompt on startup. Use !reload to pick up changes without restarting.

Security

• Only ALLOWED_SENDER can send commands. All other senders are silently ignored.
• The bot has full shell access on the host it runs on — treat it like SSH.
• Keep your .env file private and never commit it.

License

MIT