qwen-stack

qwen-coprocessor-stack

Locally-hosted Qwen 3.6 wired into Claude Code as an MCP coprocessor. Claude Code runs unmodified with normal subscription auth; Qwen is exposed as a small set of MCP tools that Claude can call to delegate cheap or bulk work to long-lived, supervised inference sessions.

The supervisor is a TypeScript MCP server (mcp-bridges/qwen-agent-server) that manages session lifecycle, backend routing, KV-cache affinity, and permission gating on top of @qwen-code/sdk. Any OpenAI-compatible endpoint serving a Qwen 3.6 GGUF works as a backend; the standard deployments are llama.cpp Metal on Apple Silicon (Qwen 3.6 27B) and llama.cpp Vulkan on AMD Strix Halo (Qwen 3.6 35B-A3B).

Full design rationale: docs/rdr/RDR-001.

Requirements

• For the supervisor (the Mac running Claude Code): Node.js 24+, npm, and Claude Code installed and signed in. Portable; not Apple-specific.
• For at least one inference backend (any OpenAI-compatible endpoint serving a Qwen 3.6 GGUF):
  • The bundled local-Mac path (scripts/setup-mac-host.sh, scripts/start-stack.sh) builds llama.cpp with Metal and runs Qwen 3.6 27B at localhost:8080. Apple Silicon, ~25 GB free disk.
  • Or a remote backend you provision separately — e.g. llama.cpp Vulkan on a Strix Halo box exposing the model at host:port/v1, reached over Tailscale or any other network you trust.

Quick start

# 1. Build llama.cpp with Metal support and download Qwen 3.6 27B (~25 GB).
./scripts/setup-mac-host.sh

# 2. Start llama-server (cold start: ~5 min off external SSD, ~5 s off NVMe).
./scripts/start-stack.sh

# 3. Build the supervisor (compiles dist/server.js — postinstall runs tsc).
( cd mcp-bridges/qwen-agent-server && npm install )

# 4. Register the supervisor with Claude Code. Either:
#    a) install as a plugin (recommended — see "Install as a plugin" below), or
#    b) run ./scripts/setup-qwen-agent-server.sh (legacy `claude mcp add` path).

# 5. Run Claude Code anywhere — the qwen_* tools are now available.
claude

To shut down the local llama-server: ./scripts/stop-stack.sh.

Install as a plugin

This repo doubles as a Claude Code plugin (qwen-stack). After npm install in step 3:

# From any shell with the claude CLI on PATH:
claude plugin marketplace add /path/to/this/repo
claude plugin install qwen-stack@qwen-stack
# Then reload from any CC session: /reload-plugins

The plugin manifest at .claude-plugin/plugin.json registers the supervisor's MCP server with ${CLAUDE_PLUGIN_ROOT} resolved to the plugin install location, so paths stay portable.

Migrating from the old qwen-coprocessor-stack plugin name (pre-0.3.0):

claude plugin uninstall qwen-coprocessor-stack
claude plugin marketplace remove qwen-coprocessor-stack
claude plugin marketplace add /path/to/this/repo
claude plugin install qwen-stack@qwen-stack

Slash commands

State lives at ~/.qwen-coprocessor-stack/config.json (object form, forward-extensible — backends, default_extensions today).

Command	Purpose
/qwen-stack:status	One-glance overview — plugin version, supervisor process, build freshness, backends + health, env overrides, red flags
/qwen-stack:backends list | add | remove | test	Backend lifecycle — edits config file in place; supervisor hot-applies on next spawn
/qwen-stack:extensions list | info <name>	Read-only listing of installed Qwen Code extensions with version, source, enabled state, declared commands/skills/agents/MCP servers
/qwen-stack:defaults list | set <a,b,c> | set --none | clear	Manage the session-default extension list applied when a spawn doesn't specify opts.extensions.only
/qwen-stack:budget list | set [--max-context-tokens N] [--max-tool-calls M] | clear [field]	Manage the session_budget caps that abort a runaway session before the HTTP layer panics

Resolution priorities (env > file > default):

• Backends: QWEN_BACKENDS env → config.backends → built-in single-local default.
• Default extensions: QWEN_DEFAULT_EXTENSIONS env → config.default_extensions → CLI defaults from extension-enablement.json.

Existing in-flight sessions stay pinned to their backend and resolved extension set (RDR-001 §Q3, RDR-002 §drain semantics) — config edits affect new spawns only.

Session budget

The inner Qwen has no automatic mid-flight compaction; an open-ended task that reads dozens of files can accumulate tool_result payload past the backend's context window and crash the HTTP layer with ECONNRESET. v0.4 adds a guardrail that aborts the session cleanly before that happens.

Two caps, both per session: