README.md
July 3, 2026 · View on GitHub
Clawd Mobile
Android companion for Clawd on Desk — a cyberpunk desktop pet that reacts to your AI coding agent in real time.
简体中文 · 繁體中文 · 日本語 · 한국어 · Desktop Version
Your pet reacts in real time — Thinking · Working · Approval · Done
🙏 致敬原作者
本项目基于 rullerzhou-afk/clawd-on-desk（Clawd on Desk）桌面端开发。原项目由 @rullerzhou-afk（鹿鹿 / Ruller_Lulu）创建——一只住在你桌面上的小螃蟹，实时感知 AI 编码 Agent 的每一个呼吸。
📖 Table of Contents
- What is Clawd Mobile?
- Features
- Screenshots
- Quick Start
- Architecture
- Communication Protocol
- Development
- Contributing
- What's Next · 未来功能
- Roadmap
- FAQ
- Contributors
- License
- Acknowledgements
🐾 What is Clawd Mobile?
Clawd Mobile is a native Android client that connects to Clawd on Desk desktop pet. It monitors your AI coding agent's activity in real time — via LAN or remote relay — and displays a live animated pet on your phone screen that reacts to what your agent is doing.
| Feature | How it works | Experience |
|---|---|---|
| Millisecond state sync | WebSocket + StateFlow pipeline, < 200ms latency | Your crab starts typing the moment your agent does |
| Pure character isolation | Server-side displayState + PetStateManager engine | 3 characters (Crab/Cat/Cloud) with independent state mapping |
| Ultra-low power | WifiLock + WakeLock + 30s watchdog + exponential backoff (1s→30s) | < 50mW background power, lasts all day |
| Overlay approval | Swipe-to-approve permission requests directly on the floating bubble | No need to open the app |
| Remote relay | Connect via VPS relay for non-LAN environments | Monitor your agent from anywhere |
✨ Features
Core Experience
- 🐾 Animated floating pet — SVG/APNG with CSS animations (breathe, blink, tail-sway)
- 📱 16 states — Working, Thinking, Idle, Sleeping, Error, Notification, and more
- 🎯 Smart sleep sequence — Yawning → Dozing → Collapsing → Sleeping with random idle variants
- 🏆 Happy celebration — 1.5s animation when a task completes
v0.10.0 — Latest Release
- 🐾 Overlay approval bubble — Approve/deny permission requests by swiping on the floating bubble
- 🌐 Remote relay — Connect via VPS relay server for non-LAN environments
- 🌍 In-app language switch — Chinese/English, switch without restarting
- 🔒 Security hardening — Encrypted storage, TOFU cert pinning, log stripping
- 🧪 548 tests — All passing, 103 new tests added
📸 Screenshots
Screenshots coming soon. The app shows a live animated pet on your phone screen that reacts to your AI agent's activity in real time — thinking, working, waiting for approval, and celebrating when a task completes.
| Floating pet | Approval bubble | Settings |
|---|---|---|
| Screenshot | Screenshot | Screenshot |
⚡ Quick Start
Prerequisites
- Android 8.0+ (API 26) device with arm64-v8a
- Clawd on Desk running on your PC
Installation
- Download the latest
app-release.apkfrom Releases - Install the APK on your Android device
- Open the app and scan the QR code displayed on your PC, or manually enter the connection details
- Grant the requested permissions (notifications, camera, overlay)
- Your pet is now live! 🎉
Connection Methods
| Method | When to use |
|---|---|
| QR Code Scan | PC and phone on the same LAN — fastest setup |
| Manual Input | Enter PC's IP, port, and token manually |
| Remote Relay | Connect via VPS relay for non-LAN environments |
🏛️ Architecture
Clawd Mobile follows a single-pipe architecture where all state changes flow through one unified StateFlow:
PC (WebSocket) → StreamingClient → PetStateManager → FloatingPetService
↓
StateCommand (single pipe)
↓
SvgLoader → FloatingPetView (WebView SVG)
Key design decisions:
- Single-pipe eliminates concurrent SVG loading race conditions
- Template method pattern (
StreamingClient→AbstractStreamingClient→WsClient) for easy transport extension - Strategy pattern (
ConnectionStrategy) for LAN/Relay connection decoupling - SessionMerger unifies LAN + Relay sessions into one view
For detailed architecture documentation, see android/README.md.
📡 Communication Protocol
WebSocket: ws://<host>:23334/mobile/ws
Approval: POST http://<host>:23334/mobile/approve
Deep Link: clawd://<host>:<port>/<token>
| Message Type | Direction | Description |
|---|---|---|
ping | Server → Client | Heartbeat |
connected | Server → Client | Connection confirmed |
snapshot | Server → Client | Full session list |
state | Server → Client | Single session update |
permission_request | Server → Client | Approval request |
reaction | Server → Client | SVG reaction animation |
🔧 Development
Environment
- Android Studio Hedgehog (2023.1.1)+
- JDK 17
- Android SDK 35
- arm64-v8a device or emulator
Build
cd android
# Debug APK
./gradlew assembleDebug
# Release APK (requires signing config)
KEYSTORE_FILE=release.keystore \
STORE_PASSWORD=xxx \
KEY_ALIAS=clawd \
KEY_PASSWORD=xxx \
./gradlew assembleRelease
# Run tests (548 tests)
./gradlew testDebugUnitTest
CI/CD
Push to main with changes in android/ triggers GitHub Actions: lint → build → test → artifact upload.
🤝 Contributing
Clawd on Mobile is a derivative project based on Clawd on Desk, adding an Android companion app, overlay approval, remote relay, and more on top of the desktop version.
To contribute, please refer to CONTRIBUTING.md.
Bug reports, feature ideas, and pull requests are all welcome — open an issue to discuss or submit a PR directly.
Maintainers
 @rullerzhou-afk 鹿鹿 · creator |
 @YOIMIYA66 maintainer |
 @Bynlk core contributor · Mobile / PWA |
Contributors
Thanks to everyone who has helped make Clawd better:
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feat/my-feature - Commit with clear messages:
git commit -m "feat: add my feature" - Push to your fork:
git push origin feat/my-feature - Open a Pull Request
Guidelines
- Follow Kotlin coding conventions
- Add tests for new features
- Update documentation if needed
- Reference related issues in your PR description
See CONTRIBUTING.md for detailed guidelines.
🔮 What's Next · 未来功能
Clawd Mobile already lets you watch your agent and approve permissions over the LAN or a self-hosted relay. Two bigger capabilities are on the way — both aim at the same goal: stay in control of your agent even when you're away from your desk.
1. 🌐 Hosted server relay · 服务器中继（出门在外也能审批）
Today's relay is something you deploy yourself on a VPS. The next step is a turn-key, always-on relay so your phone stays connected to your desktop agent no matter where you are — different network, cellular data, or on the road. When your agent hits a permission request while you're out, the approval bubble reaches your phone and you can Allow / Deny on the go, without being on the same Wi-Fi and without any manual server setup.
- Approve / deny permission requests from anywhere, over cellular
- Zero-config connection — no self-hosted VPS required
- End-to-end secured, building on the existing TOFU cert-pinning foundation
2. 📬 Content push · 内容推送（1:1 同步终端显示）
Beyond animated state, we want the phone to mirror what the terminal actually shows — 1:1 — so you can read what your agent is doing, not just infer it from the pet's mood. The exact scope, delivery format, and privacy model are still under discussion, and this section will be filled in once the design settles.
💡 Have thoughts on either feature? Open an issue or a discussion — feedback is very welcome while these are still being shaped.
🗺️ Roadmap
| Priority | Item | Status |
|---|---|---|
| ✅ | WebSocket migration (from SSE) | Done |
| ✅ | TOFU certificate pinning | Done |
| ✅ | Overlay approval bubble | Done |
| ✅ | Remote relay support (self-hosted) | Done |
| ✅ | In-app language switch | Done |
| ✅ | Security hardening | Done |
| 🔄 | Hilt dependency injection | Planned |
| 🔄 | Repository pattern | Planned |
| 🔄 | AbstractStreamingClient tests | Planned |
| 🔮 | Hosted server relay (approve anywhere) | Exploring |
| 🔮 | Content push (1:1 terminal mirror) | Under discussion |
See android/docs/ROADMAP.md for the full roadmap.
❓ FAQ
Q: Do I need the desktop app? A: Yes. Clawd Mobile is a companion app — it connects to Clawd on Desk running on your PC.
Q: Can I use it outside my home network? A: Yes! v0.10.0 added remote relay support. Deploy a relay server on your VPS and connect from anywhere.
Q: Which AI agents are supported? A: Any agent that works with Clawd on Desk — Claude Code, Codex, Cursor, Copilot, Gemini, and more.
Q: The pet doesn't move / stays on idle A: Make sure your desktop app is connected and has an active session. Check the connection status in the app's settings.
Q: How do I update? A: Download the latest APK from Releases and install over the existing app. Your data will be preserved.
👥 Contributors
Android Port
- @Bynlk — Android port developer & maintainer
Desktop Contributors
The following developers have contributed to the Clawd ecosystem (desktop + mobile):
| Contributor | Contribution |
|---|---|
| @rullerzhou-afk (鹿鹿) | Original creator of Clawd on Desk |
| @Ruller_Lulu | Core development |
| @Yoimiya | Major contributions |
| @Lyu Bingrong | Features & fixes |
| @hwasowl | Features & fixes |
| @nmsn | Features & fixes |
| @zxypro | Telegram approval status |
| @sLingli | Reasonix CLI integration |
| @cod3hulk | tmux focus support |
| @lxgxhsy | Windows focus cache |
| @rebootcrab-blip | Agent asar packaging fix |
| @ustin-star | CodeWhale adapter |
| @zhangzhengtian02 | Features & fixes |
| @Wei Lai | Features & fixes |
| @Yi-Jyun Pan | Features & fixes |
| @Zone Tome | Features & fixes |
| @LI SHANXIN | Features & fixes |
| @PixelCookie | Features & fixes |
| @Steven Chen | Features & fixes |
| @Tao Xie | Features & fixes |
| @Zhengru | Features & fixes |
| @tatsuyanakano | Features & fixes |
| @yeqiyeluo | Features & fixes |
| @正如 | Features & fixes |
| @张星宇 | Features & fixes |
| @Wei Lai | Features & fixes |
🙏 感谢所有为 Clawd 项目做出贡献的开发者！ 无论是代码、文档、Bug 报告还是功能建议，每一份贡献都让这个项目变得更好。
If you've contributed and your name is missing, please open an issue or PR to add yourself.
📄 License
- Code: AGPL-3.0
- Art assets: All Rights Reserved
Clawd is a character owned by Anthropic. This is an unofficial fan project, not affiliated with or endorsed by Anthropic.
🙏 Acknowledgements
-
rullerzhou-afk (鹿鹿 / Ruller_Lulu) — Creator of Clawd on Desk, the desktop pet that started it all. Thank you for creating this amazing project and making it open source.
-
Anthropic — For creating Claude, the AI that inspired this project.
-
All contributors — Thank you for your time, code, and passion.
-
The open source community — For the tools and libraries that made this possible: Kotlin, Jetpack Compose, OkHttp, kotlinx.serialization, CameraX, ZXing, and many more.
⭐ If you like this project, give it a star on GitHub!