A hardware-neutral guide to three open-source ways of connecting coding-agent runtimes to Buzz through the Agent Client Protocol (ACP).
These projects separate the user-facing agent harness from model inference. Buzz and the harness normally run on the user's computer; the model can run locally, on a workstation, across a cluster, in containers, or behind a hosted API. Pick the harness for its agent behavior and protocol compatibility, then pick the model-serving hardware independently.
- Buzz DeepSeek Harness — a small, direct ACP bridge for OpenAI-compatible coding models.
- Buzz Qwen Code Harness — Qwen Code as the agent runtime, plus a backup-safe grammar-compatibility patcher.
- Buzz ZCode Harness — an attributed fork of
zcode-acpwith Buzz installation, provider, MCP-auth, and cancellation fixes.
Each project has its own installation, test, security, update, and troubleshooting guide. This repository is the comparison and decision layer; it does not install all three at once.
| Capability | DeepSeek harness | Qwen Code harness | ZCode harness |
|---|---|---|---|
| Agent runtime | Purpose-built JavaScript ACP bridge | Qwen Code | ZCode app-server through an attributed zcode-acp fork |
| Model connection | Direct OpenAI-compatible /v1 endpoint |
Qwen Code's OpenAI-compatible configuration | Providers and credentials managed by ZCode |
| Model location | Local, LAN, cluster, container, or hosted | Local, LAN, cluster, container, or hosted | Local, LAN, cluster, container, or hosted, as supported by the configured ZCode provider |
| Model family | Not restricted to DeepSeek; use a compatible coding/tool model | Not restricted to Qwen; use a Qwen Code-compatible endpoint and model | Any model present in ZCode's valid provider registry |
| Model discovery | Queries the configured endpoint and exposes usable IDs | Uses the configured model ID and endpoint | Reads ZCode's configured models; empty providers are omitted |
| Tool ownership | Bridge exposes and mediates its own ACP/MCP tool surface | Qwen Code supplies its coding tools | ZCode supplies tools; bridge translates its events and interactions to ACP |
| Grammar compatibility | Schema proxy/cap for servers with constrained grammar limits | Syntax-aware patch of actual Qwen tool schemas only | No Qwen bundle patch; compatibility depends on ZCode and its provider |
| MCP behavior | Compatibility layer rejects unsupported client fields and mediates supported servers | Qwen Code's MCP/tool support plus Buzz's authenticated reply sidecar | User-managed MCP works; desktop-only official auth returns a schema-valid unavailable result |
| Cancellation | Bridge and Buzz supervisor bound stale work | Qwen Code process lifecycle is supervised by Buzz | Sends stop, suppresses cancelled output, waits for terminal proof, then permits Buzz's grace-timeout restart |
| Secret handling | Runtime environment indirection; do not commit values | Manifest stores only an API-key variable name | Provider credentials stay in ZCode's credential store |
| Upstream dependency | Lightweight bridge dependencies | Installed Qwen Code release; bundles are not redistributed | Preserves and tracks william0wang/zcode-acp upstream history |
| Best fit | Maximum transparency and direct control over an OpenAI-compatible server | Users who want Qwen Code's established coding-agent behavior | Users who want ZCode's provider ecosystem, sessions, tools, and extensions |
| Main tradeoff | More behavior is maintained in the custom bridge | Installed bundle may need a version-specific grammar workaround | Larger upstream surface and tighter coupling to ZCode app-server versions |
Choose the DeepSeek harness when you want the shortest path from Buzz to an OpenAI-compatible server and prefer to inspect or customize every compatibility behavior in a compact codebase. Despite the name, the bridge can target other coding models that implement the expected streaming and tool-call protocol.
Choose the Qwen Code harness when you want Qwen Code itself to remain the agent runtime. Its patcher is useful when a llama.cpp-family server cannot construct a grammar from large Qwen tool string bounds. The tool audits first, creates a complete timestamped installation backup, changes only offending Qwen tool schemas, and verifies the result.
Choose the ZCode harness when ZCode already manages the providers and model catalog you want. It carries more upstream capability—sessions, model switching, permissions, extensions, replay, quota, and optional remote access—but it also requires compatibility testing when the ZCode app-server changes.
It is reasonable to install more than one harness for comparison, but give each Buzz agent one harness at a time. A harness definition controls how Buzz starts a runtime; an individual agent definition controls that seat's name, role, and instructions.
user computer
┌──────────────────────────────────────────────────────────┐
│ Buzz ── ACP/stdin+stdout ── selected coding harness │
└───────────────────────────────┬──────────────────────────┘
│ model/provider protocol
▼
┌────────────────────────────────────┐
│ inference service │
│ local │ LAN │ cluster │ containers │ cloud
└────────────────────────────────────┘
ACP is the client-to-agent boundary. OpenAI-compatible HTTP or a provider-specific protocol is the agent-to-model boundary. Treating them separately avoids hardware-specific setup instructions and makes failures easier to localize.
| Layer | Runs where | Hardware requirements | Portability rule |
|---|---|---|---|
| Buzz | User workstation | Whatever Buzz supports | Keep user interface concerns out of the model cluster |
| ACP harness | Usually the Buzz workstation | Node.js and the selected runtime | Use absolute executable paths because GUI apps may not inherit shell PATH |
| Model gateway | Same host or remote | Depends on serving stack | Publish one stable URL; do not expose worker topology to the harness |
| Model workers | CPU/GPU/accelerator nodes | Model- and server-specific | Tune parallelism, quantization, and memory in the server project |
| Credentials | Client secret store or runtime environment | None | Store values outside public manifests and repositories |
For a single computer, all boxes can be on loopback. For a LAN server or multi-node cluster, only the model gateway must be reachable from the harness. For a hosted provider, use TLS and the provider's supported credential injection.
Before debugging ACP, prove each boundary independently:
- The selected runtime starts from the same desktop environment Buzz uses.
- The model endpoint responds from the harness computer.
- The configured model ID exists or is accepted by the provider.
- A direct runtime prompt streams a normal text response.
- A direct runtime prompt can perform one simple tool call.
- The ACP harness initializes and reports at least one usable model.
- Buzz receives both streaming updates and a terminal turn result.
For OpenAI-compatible deployments, a generic reachability check is:
curl http://model-host.example:8000/v1/modelsFor an authenticated service:
curl -H "Authorization: Bearer $MODEL_API_KEY" \
https://provider.example/v1/modelsDo not put a real key in documentation, a harness manifest, a shell script committed to Git, or a bug report.
| Symptom | Most likely boundary | First check |
|---|---|---|
| Harness reports no models | Runtime ↔ model/provider | Model ID, provider registry, /models, and runtime environment |
| HTTP 400 before generation | Model server grammar/template | Server log and tool-schema compatibility |
| CLI works but Buzz shows nothing | Buzz ↔ ACP harness | ACP stdout purity, session updates, terminal event, and command path |
| Tool calls repeat | Model/template/tool contract | Model tool training, server chat template, and tool result framing |
| Prompt continues after cancel | Runtime/backend lifecycle | Stop acknowledgment, silent drain, grace timeout, and worker restart |
| MCP auth or parameters fail | Harness ↔ MCP contract | Supported fields, credential owner, and whether auth depends on a desktop-only service |
| Historical model names differ | Configuration timeline | Correlate log timestamps with intentional harness and agent edits |
- Bind an unauthenticated local model to loopback unless remote clients are required.
- Put authentication and TLS in front of endpoints that cross untrusted networks.
- Limit coding agents to intended workspaces and tools.
- Keep API-key values out of custom-harness JSON.
- Never publish local backups, compiled application bundles, desktop credential files, private hostnames, or logs containing prompts and file paths.
- On cancellation, prefer termination you can prove over assuming a backend obeyed stop.
- Review every installer and manifest before running it in a shared environment.
The repositories are public for inspection and reuse. Direct write access is limited to the owner; other contributions use forks and pull requests. CI runs on proposed changes, and compatibility claims should identify the versions and workflow actually tested.
Upstream projects retain their own names, licenses, and trademarks. These integrations are independent community projects and do not imply endorsement by Buzz, Qwen, ZCode, DeepSeek, or their maintainers.