{"id":48236015,"url":"https://github.com/Mihai-Codes/beeperclaw","last_synced_at":"2026-04-20T07:01:26.335Z","repository":{"id":337326050,"uuid":"1153110860","full_name":"Mihai-Codes/beeperclaw","owner":"Mihai-Codes","description":"AI coding agent accessible from anywhere via Matrix/Beeper. Self-hosted \u0026 Local-First.","archived":false,"fork":false,"pushed_at":"2026-03-24T19:08:04.000Z","size":210,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T00:29:36.870Z","etag":null,"topics":["ai-agent","beeper","matrix","opencode","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mihai-Codes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T22:51:34.000Z","updated_at":"2026-03-24T19:08:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Mihai-Codes/beeperclaw","commit_stats":null,"previous_names":["mihai-codes/codebeep","mihai-codes/beeperclaw"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Mihai-Codes/beeperclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mihai-Codes%2Fbeeperclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mihai-Codes%2Fbeeperclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mihai-Codes%2Fbeeperclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mihai-Codes%2Fbeeperclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mihai-Codes","download_url":"https://codeload.github.com/Mihai-Codes/beeperclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mihai-Codes%2Fbeeperclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32036799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","beeper","matrix","opencode","python"],"created_at":"2026-04-04T20:00:26.649Z","updated_at":"2026-04-20T07:01:26.328Z","avatar_url":"https://github.com/Mihai-Codes.png","language":"Python","funding_links":[],"categories":["🧠 AI \u0026 Agents"],"sub_categories":[],"readme":"# beeperclaw\n\n\u003e Your AI coding agent, accessible from anywhere via Matrix/Beeper.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n\n**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.\n\nInspired by [OpenClaw](https://github.com/openclaw/openclaw) - a personal AI assistant that runs on your own devices and answers on channels you already use.\n\n## Why beeperclaw?\n\n| Feature | Cursor Slack | Copilot Slack | beeperclaw |\n|---------|--------------|---------------|----------|\n| Self-hosted | No | No | **Yes** |\n| Open Source | No | No | **Yes** |\n| Privacy | Cloud | Cloud | **Local** |\n| Platform | Slack only | Slack only | **Matrix/Beeper** |\n| AI Provider | Cursor models | GitHub models | **Any (Antigravity, Copilot, etc.)** |\n| Cost | Paid | Paid | **Free*** |\n\n*Free when using Antigravity Manager with Google AI Studio quotas\n\n## Features\n\n- **Mobile-first**: Assign coding tasks from your phone via Beeper/Matrix\n- **Attachment Context**: Send screenshots or files from Beeper and use them in `/build` or `/plan`\n- **OpenCode Integration**: Full access to OpenCode's build and plan agents\n- **Self-hosted**: Your code, your data, your control\n- **Unencrypted Shell Room**: Dedicated room for reliable command execution\n- **Error Resilience**: Handles rate limiting and transient failures gracefully\n- **Multi-Provider Support**: Works with any OpenCode-compatible AI provider\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- Matrix account (either [Beeper](https://beeper.com) or [matrix.org](https://matrix.org))\n- [OpenCode](https://opencode.ai) installed and configured\n\n## Remote CLI\n\nSee the phone-friendly mosh + tmux guide: [docs/remote-cli.md](docs/remote-cli.md)\n\nIf you set `bot.connect_host`, the bot can also reply with the configured connect string via `/ssh` or `/mosh`.\n\n**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.\n\n### Installation\n\n#### Method 1: Docker (Recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/Mihai-Codes/beeperclaw.git\ncd beeperclaw\n\n# Build and run with Docker (solves python-olm compilation issues)\ndocker-compose up -d\n\n# Check logs\ndocker-compose logs -f\n```\n\n#### Method 2: Native Python\n```bash\n# Clone the repository\ngit clone https://github.com/Mihai-Codes/beeperclaw.git\ncd beeperclaw\n\n# Create virtual environment and install\npython3 -m venv venv\nsource venv/bin/activate\npip install -e .\n\n# Configuration\ncp config.example.yaml config.yaml\n# Edit config.yaml with your Beeper credentials\n```\n\n### Auto-Start Options\n\n#### Option 1: Docker (Recommended - Solves python-olm issues)\n```bash\n# Build and run with Docker\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop\ndocker-compose down\n```\n\n#### Option 2: macOS LaunchAgent\nThis project includes a LaunchAgent to keep the bot running in the background.\n\n1. **Install the Service:**\n   ```bash\n   cp com.mihai.beeperclaw.plist ~/Library/LaunchAgents/\n   launchctl load ~/Library/LaunchAgents/com.mihai.beeperclaw.plist\n   ```\n\n2. **Check Logs:**\n   ```bash\n   tail -f /tmp/beeperclaw.log\n   tail -f /tmp/beeperclaw.error.log\n   ```\n\n## Configuration\n\nEdit `config.yaml` (Beeper account):\n\n```yaml\nmatrix:\n  homeserver: \"https://matrix.beeper.com\"\n  username: \"@your-bot:beeper.local\"\n  password: \"your-password\"  # or use access_token\n\nopencode:\n  server_url: \"http://127.0.0.1:4096\"\n  default_agent: \"build\"\n```\n\nEdit `config.yaml` (matrix.org account):\n\n```yaml\nmatrix:\n  homeserver: \"https://matrix-client.matrix.org\"\n  username: \"@your-bot:matrix.org\"\n  password: \"your-password\"  # or use access_token\n```\n\n### Matrix.org fallback (no Beeper+ required)\n\nIf you can’t create a second Beeper account, you can run the bot on matrix.org and DM it from Beeper Desktop/Android.\n\n1. Create a Matrix account for the bot on matrix.org (Element signup is fine).\n2. Exchange username/password for an access token:\n\n```bash\ncurl -s https://matrix-client.matrix.org/_matrix/client/v3/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\":\"m.login.password\",\n    \"user\":\"@beeperclaw-bot:matrix.org\",\n    \"password\":\"YOUR_BOT_PASSWORD\"\n  }'\n```\n\n3. Copy `access_token` into `.env` and restart:\n\n```bash\nBEEPER_ACCESS_TOKEN=PASTE_MATRIX_TOKEN_HERE\ndocker compose up -d\n```\n```\n\n## Architecture\n\n```\nPhone (Beeper App)\n        │\n        │ Matrix Protocol (E2EE)\n        ▼\nbeeperclaw Bot (Docker)\n        │\n        ├──► OpenCode Server (:4096)\n        │         │\n        │         └──► AI Agents (build, plan, general, etc.)\n        │                   │\n        │                   └──► MCP Tools, Code Execution\n        │\n        └──► Matrix Rooms\n                  │\n                  └──► BeeperClaw Shell (unencrypted)\n                            │\n                            └──► Command Interface\n```\n\n## Available Commands\n\n- `/build \u003ctask\u003e` - Execute a coding task with full file access\n- `/plan \u003crequest\u003e` - Analyze code without making changes\n- `/status` - Check current session status\n- `/agents` - List available AI agents\n- `/ssh` - Show configured SSH and mosh connection strings\n- `/sessions` - List all sessions\n- `/help` - Show help information\n\nYou 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.\n\n## Current Status\n\n**Working**: Basic commands (/help, /status, /agents), Docker deployment  \n**In Progress**: Action commands (/build, /plan) - working but may have occasional errors\n\n## Known Issues\n\n- Room creation may fail due to Matrix rate limiting (retries implemented)\n- Some API response formats may cause intermittent errors (being addressed)\n\n## Roadmap\n\nPlanned improvements are tracked in GitHub Issues:\n\n1. Persistent KeyError investigation\n2. Session state persistence\n3. Robust error handling\n4. Room creation reliability\n5. Message deduplication\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Note**: This project is not built by the OpenCode team and is not affiliated with them in any way.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMihai-Codes%2Fbeeperclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMihai-Codes%2Fbeeperclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMihai-Codes%2Fbeeperclaw/lists"}