# devbell-for-workbudy
**Repository Path**: xqtang/devbell-for-workbudy
## Basic Information
- **Project Name**: devbell-for-workbudy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-08
- **Last Updated**: 2026-11-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
English · 简体中文
# DevBell for WorkBuddy
DevBell for WorkBuddy connects a WorkBuddy project to the
[DevBell](https://gitee.com/xqtang/devbell-bridge) AI Passport handheld. The
handheld displays what the agent is doing and speaks when a human must return
to the computer to answer, choose, or inspect a result.
## What it provides
- A text-and-voice status channel separate from the WorkBuddy chat window
- Task-start, confirmation, choice, completion, and error signals driven by
project-level `AGENTS.md`
- Offline-safe behavior: DevBell failures never block agent work
- A dependency-free HTTP integration with the local DevBell bridge
## Architecture
```text
WorkBuddy agent session
|
| AGENTS.md injected as project context (WorkBuddy has no hook system;
| the managed section IS the enforcement mechanism)
| HTTP on 127.0.0.1:8765
v
devbell-bridge
|
| Bluetooth Low Energy
v
AI Passport running DevBell firmware
```
## Why there are no hooks
WorkBuddy reads `AGENTS.md` — it is injected into every session as project
context — but WorkBuddy has **no hook system**: there is no automatic
enforcer for state pushes. Two consequences:
1. The AGENTS.md protocol is carried by injection alone. Treat every push as a
mandatory step, not a decoration.
2. WorkBuddy's own tool-approval dialog cannot be detected by AGENTS.md. The
protocol therefore covers the *conversation* interaction path (the agent
pushing `waiting_confirm` before asking a Yes/No question in chat), and
deployment reports must state this limitation honestly.
## Platform notes for WorkBuddy agent shells (hard-won, do not skip)
1. **Proxy trap.** Agent shells often carry `HTTP_PROXY` pointing at a local
sandbox proxy. Requests to `127.0.0.1:8765` then return a fake
`502 Bad Gateway` even when the bridge is healthy. Always export
`NO_PROXY=127.0.0.1,localhost` (and lowercase) before any devbell command.
A 502 means the proxy answered, not the bridge.
2. **CLI not on PATH.** On macOS the WorkBuddy-bundled Python lives at
`~/.workbuddy/binaries/python//bin/`; `devbell` is installed there
and is not on the default PATH of agent shells. Export
`PATH="$HOME/.workbuddy/binaries/python/versions//bin:$PATH"`.
3. **launchd restriction (macOS).** Shells spawned by the WorkBuddy desktop app
cannot register launchd jobs — `launchctl bootstrap/load/submit` all fail
with error 5, even for a trivial plist, even unsandboxed. Registering
autostart is a HUMAN action in Terminal.app. The shipped
`devbell-bridge.macos.plist` also needs two fixes before install: replace
the hardcoded `/usr/bin/python3` (no package there) with the absolute path
of the interpreter that pip installed into, and replace the `$(USER)` in
`StandardOutPath` (launchd does not expand it) with the literal home path.
4. **Linux/Windows** behave as documented by the bridge project (systemd user
service / Startup folder); the agent shell can install those itself.
## Repository contents
| File | Purpose |
| --- | --- |
| `README.md` / `README.zh_CN.md` | This document |
| `AGENTS.md` | The DevBell status-sync rules (injected into every WorkBuddy session) |
| `devbell-quickstart.md` / `.zh_CN.md` | Step-by-step onboarding for a new project |
| `devbell-deploy-new-project-prompt.md` | Paste-into-chat deployment prompt |
| `LICENSE` | MIT license |
## Requirements
- WorkBuddy opened on the project directory
- An AI Passport running DevBell firmware, charged, powered on, in range
- An installed and running `devbell-bridge`
- The handheld must not already be connected to another BLE host
## Quick start
1. Check the bridge (in any shell, with the platform notes applied):
```bash
export NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost
devbell health
```
A ready bridge returns `{"ok":true,"connected":true}`.
2. Paste [devbell-deploy-new-project-prompt.md](devbell-deploy-new-project-prompt.md)
into WorkBuddy with the new project open. It installs or reuses the bridge,
hands macOS autostart to the human, verifies the device link, and merges the
DevBell section into the project's `AGENTS.md`.
3. Start a fresh WorkBuddy session and verify:
```text
Read AGENTS.md and follow the DevBell status-sync rules. Check the bridge
health first. Then perform a small read-only verification task for this
project and finish with a DevBell done state.
```
The handheld should show blue `Working`, then green `Done`.
See [devbell-quickstart.md](devbell-quickstart.md) for the full walkthrough,
including the human-interaction test.
## States and prompts
| State | Handheld | Voice / behavior |
| --- | --- | --- |
| `idle` | Gray `Idle` | Silent |
| `working` | Blue `Working` | Silent |
| `waiting_confirm` | Orange pulsing `Confirm` | Speaks, then reminds every 20 s, up to 3 |
| `waiting_choice` | Orange pulsing `Choose` | Speaks, then reminds every 20 s, up to 3 |
| `done` | Green `Done` | Speaks once, visible about 17 s |
| `error` | Red `Error` | Speaks once |
Pressing OK on the handheld silences the local prompt; it does not answer the
agent — answer in the WorkBuddy conversation.
## Message conventions
- Messages are limited to 180 UTF-8 bytes.
- Chinese characters select Chinese; ASCII-only messages select English.
- Status pushes are best-effort standalone commands; success is
`acked: true`, `accepted: true`, `result: 0`.
## HTTP API
| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Check the bridge and BLE connection |
| `GET` | `/status` | Read the current device snapshot |
| `POST` | `/status` | Push a state and message |
| `POST` | `/config` | Change volume, mute, or language |
| `POST` | `/ping` | Check round-trip liveness |
## Troubleshooting
| Symptom | Action |
| --- | --- |
| Fake `502 Bad Gateway` on localhost | The proxy intercepted it; export `NO_PROXY=127.0.0.1,localhost` and retry |
| Connection refused on port 8765 | Ask the human to run `launchctl load` once in Terminal.app (macOS); do not run the bridge in the foreground |
| `connected: false` | Check power, charge, range, and other BLE connections |
| `devbell: command not found` | Export the WorkBuddy python bin dir onto PATH, or use `python3 -m devbell_bridge.cli` |
| WorkBuddy never changes the handheld state | Confirm `AGENTS.md` is in the opened workspace root and start a fresh session |
| No sound | Check handheld volume and mute |
| Handheld stays on `Confirm` after answering | The agent must re-push `working` after the answer |
| Port 8765 already in use | Reuse the running bridge; never start a second instance |
## Related links
- [DevBell bridge](https://gitee.com/xqtang/devbell-bridge)
## License
This project is released under the [MIT License](LICENSE).