https://github.com/Mihai-Codes/beeperclaw
AI coding agent accessible from anywhere via Matrix/Beeper. Self-hosted & Local-First.
https://github.com/Mihai-Codes/beeperclaw
ai-agent beeper matrix opencode python
Last synced: about 2 months ago
JSON representation
AI coding agent accessible from anywhere via Matrix/Beeper. Self-hosted & Local-First.
- Host: GitHub
- URL: https://github.com/Mihai-Codes/beeperclaw
- Owner: Mihai-Codes
- License: mit
- Created: 2026-02-08T22:51:34.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T19:08:04.000Z (3 months ago)
- Last Synced: 2026-03-26T00:29:36.870Z (3 months ago)
- Topics: ai-agent, beeper, matrix, opencode, python
- Language: Python
- Homepage:
- Size: 205 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-beeper - CodeBeep
README
# beeperclaw
> Your AI coding agent, accessible from anywhere via Matrix/Beeper.
[](https://opensource.org/licenses/MIT)
**beeperclaw** is a self-hosted AI coding agent that lets you assign coding tasks from your phone via [Beeper](https://beeper.com) (Matrix protocol). It integrates with [OpenCode](https://opencode.ai) to provide the same powerful coding capabilities you have on desktop, but accessible from anywhere.
Inspired by [OpenClaw](https://github.com/openclaw/openclaw) - a personal AI assistant that runs on your own devices and answers on channels you already use.
## Why beeperclaw?
| Feature | Cursor Slack | Copilot Slack | beeperclaw |
|---------|--------------|---------------|----------|
| Self-hosted | No | No | **Yes** |
| Open Source | No | No | **Yes** |
| Privacy | Cloud | Cloud | **Local** |
| Platform | Slack only | Slack only | **Matrix/Beeper** |
| AI Provider | Cursor models | GitHub models | **Any (Antigravity, Copilot, etc.)** |
| Cost | Paid | Paid | **Free*** |
*Free when using Antigravity Manager with Google AI Studio quotas
## Features
- **Mobile-first**: Assign coding tasks from your phone via Beeper/Matrix
- **Attachment Context**: Send screenshots or files from Beeper and use them in `/build` or `/plan`
- **OpenCode Integration**: Full access to OpenCode's build and plan agents
- **Self-hosted**: Your code, your data, your control
- **Unencrypted Shell Room**: Dedicated room for reliable command execution
- **Error Resilience**: Handles rate limiting and transient failures gracefully
- **Multi-Provider Support**: Works with any OpenCode-compatible AI provider
## Quick Start
### Prerequisites
- Python 3.11+
- Matrix account (either [Beeper](https://beeper.com) or [matrix.org](https://matrix.org))
- [OpenCode](https://opencode.ai) installed and configured
## Remote CLI
See the phone-friendly mosh + tmux guide: [docs/remote-cli.md](docs/remote-cli.md)
If you set `bot.connect_host`, the bot can also reply with the configured connect string via `/ssh` or `/mosh`.
**Beeper note:** Starting a new Matrix DM from Beeper is supported on Desktop and Android, but is still a work in progress on iOS. If you plan to message a `@bot:matrix.org` account from Beeper, use Desktop or Android for the first DM. See Beeper’s Matrix chat guide for details.
### Installation
#### Method 1: Docker (Recommended)
```bash
# Clone the repository
git clone https://github.com/Mihai-Codes/beeperclaw.git
cd beeperclaw
# Build and run with Docker (solves python-olm compilation issues)
docker-compose up -d
# Check logs
docker-compose logs -f
```
#### Method 2: Native Python
```bash
# Clone the repository
git clone https://github.com/Mihai-Codes/beeperclaw.git
cd beeperclaw
# Create virtual environment and install
python3 -m venv venv
source venv/bin/activate
pip install -e .
# Configuration
cp config.example.yaml config.yaml
# Edit config.yaml with your Beeper credentials
```
### Auto-Start Options
#### Option 1: Docker (Recommended - Solves python-olm issues)
```bash
# Build and run with Docker
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
#### Option 2: macOS LaunchAgent
This project includes a LaunchAgent to keep the bot running in the background.
1. **Install the Service:**
```bash
cp com.mihai.beeperclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.mihai.beeperclaw.plist
```
2. **Check Logs:**
```bash
tail -f /tmp/beeperclaw.log
tail -f /tmp/beeperclaw.error.log
```
## Configuration
Edit `config.yaml` (Beeper account):
```yaml
matrix:
homeserver: "https://matrix.beeper.com"
username: "@your-bot:beeper.local"
password: "your-password" # or use access_token
opencode:
server_url: "http://127.0.0.1:4096"
default_agent: "build"
```
Edit `config.yaml` (matrix.org account):
```yaml
matrix:
homeserver: "https://matrix-client.matrix.org"
username: "@your-bot:matrix.org"
password: "your-password" # or use access_token
```
### Matrix.org fallback (no Beeper+ required)
If you can’t create a second Beeper account, you can run the bot on matrix.org and DM it from Beeper Desktop/Android.
1. Create a Matrix account for the bot on matrix.org (Element signup is fine).
2. Exchange username/password for an access token:
```bash
curl -s https://matrix-client.matrix.org/_matrix/client/v3/login \
-H "Content-Type: application/json" \
-d '{
"type":"m.login.password",
"user":"@beeperclaw-bot:matrix.org",
"password":"YOUR_BOT_PASSWORD"
}'
```
3. Copy `access_token` into `.env` and restart:
```bash
BEEPER_ACCESS_TOKEN=PASTE_MATRIX_TOKEN_HERE
docker compose up -d
```
```
## Architecture
```
Phone (Beeper App)
│
│ Matrix Protocol (E2EE)
▼
beeperclaw Bot (Docker)
│
├──► OpenCode Server (:4096)
│ │
│ └──► AI Agents (build, plan, general, etc.)
│ │
│ └──► MCP Tools, Code Execution
│
└──► Matrix Rooms
│
└──► BeeperClaw Shell (unencrypted)
│
└──► Command Interface
```
## Available Commands
- `/build ` - Execute a coding task with full file access
- `/plan ` - Analyze code without making changes
- `/status` - Check current session status
- `/agents` - List available AI agents
- `/ssh` - Show configured SSH and mosh connection strings
- `/sessions` - List all sessions
- `/help` - Show help information
You can also upload an image or file before `/build` or `/plan`, or caption the upload with `/build ...` or `/plan ...` to run immediately with that attachment as context.
## Current Status
**Working**: Basic commands (/help, /status, /agents), Docker deployment
**In Progress**: Action commands (/build, /plan) - working but may have occasional errors
## Known Issues
- Room creation may fail due to Matrix rate limiting (retries implemented)
- Some API response formats may cause intermittent errors (being addressed)
## Roadmap
Planned improvements are tracked in GitHub Issues:
1. Persistent KeyError investigation
2. Session state persistence
3. Robust error handling
4. Room creation reliability
5. Message deduplication
## License
MIT License - see [LICENSE](LICENSE) for details.
---
**Note**: This project is not built by the OpenCode team and is not affiliated with them in any way.