# 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).