waxwing-mcp
Allows configuring OpenAI-compatible Chat Completions endpoints as worker providers for delegated coding tasks, with API keys sourced from the environment and tasks managed locally.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Waxwing
Waxwing is a local-first delegation manager for DeepSeek and OpenAI-compatible coding agents. A delegating Agent defines a task and acceptance criteria, a worker Agent implements it, and the delegating party independently inspects the evidence before accepting the result.
CLI, MCP stdio, and the Tauri desktop app are three adapters over one manager
listening only on 127.0.0.1. The current release is a 0.3.0 preview intended
for a trusted local user and a trusted delegating Agent, not a public or
multi-tenant service.
中文说明 · Architecture · Contributing · Security
Why Waxwing
Delegation without a control plane. Tasks stay on your machine.
Provider-neutral. Use DeepSeek Harness or any compatible OpenAI Chat Completions endpoint.
Independent acceptance. A model saying “done” is not acceptance. The delegating Agent records its own checks and evidence.
Durable round leases. Results, errors, heartbeat health, fallback, and rework are ordered by an explicit
roundIdprotocol.Workspace isolation. Clean Git repositories automatically run in sibling worktrees; non-Git directories use an exclusive shared lock.
Parallel research fan-out. One batch can send many read-only source investigations to separate execution Agents, then collect one cited report.
Unlimited by default. Request counts, tool loops, and cost limits are not blocked unless you explicitly configure a threshold.
Bounded APIs. Default CLI/MCP responses stay small; results, reports, history, usage, workspace metadata, diffs, and logs are paged on demand.
Related MCP server: Codex DSH MCP
Install
Requires Node.js 20 or newer.
waxwing is installed from the npm registry under the package name
@quanernya/waxwing:
npm install -g @quanernya/waxwing
waxwing health
waxwingThe package installs two commands:
waxwing— CLI and interactive task consolewaxwing-mcp— MCP stdio server
You can also run from a checkout:
git clone https://github.com/quanertsuki/waxwing.git
cd waxwing
node bin/waxwing.mjs healthQuick start
1. Choose a provider
The default public configuration expects DeepSeek Harness as a sibling checkout:
workspace/
waxwing/
deepseek-harness/Create a local override when your paths differ. It belongs in the per-user data
directory (%LOCALAPPDATA%\Waxwing\config.local.json on Windows,
~/Library/Application Support/Waxwing/config.local.json on macOS, and
$XDG_DATA_HOME/waxwing/config.local.json on Linux), or wherever
WAXWING_LOCAL_CONFIG points. Copy prototype/config.local.example.json
there rather than into the checkout: an update replaces the installation
directory. An older prototype/config.local.json is still read when the new
file does not exist.
For an OpenAI-compatible endpoint, copy
examples/providers/openai-compatible.json into your provider directory
(<WAXWING_HOME>/providers by default), set apiKeyEnv, and point
defaultProvider at the provider name. API keys remain in the environment and
are never copied into task data.
Request budgets are opt-in. maxToolRequests omitted, null, or 0 means no
tool-loop limit.
2. Create a task
waxwing create @task.jsonExample task.json:
{
"workspace": "C:\\work\\my-project",
"workspaceMode": "auto",
"prompt": "Implement the requested feature and run the tests.",
"plan": "Inspect, implement, test.",
"criteria": "Independent tests pass and the diff is limited to the requested behavior."
}workspaceMode accepts:
Value | Behavior |
| Clean Git repository → isolated worktree; non-Git directory → shared lock; dirty Git repository → refused |
| Require a clean Git repository and isolated worktree |
| Explicitly work in the original directory |
3. Inspect, verify, rework, accept
waxwing wait task-xxxxxxxxxxxx
waxwing wait task-xxxxxxxxxxxx --timeout 300
waxwing status task-xxxxxxxxxxxx
waxwing status task-xxxxxxxxxxxx --view result
waxwing status task-xxxxxxxxxxxx --view report
waxwing status task-xxxxxxxxxxxx --view diff
waxwing status task-xxxxxxxxxxxx --view log
waxwing rework @rework.json
waxwing accept @acceptance.json
waxwing close task-xxxxxxxxxxxxAvailable paginated views: result, history, usage, report, workspace,
diff, and log. Use --offset and --limit for large output.
wait is one server-side blocking call. It returns as soon as the task stops
running, or returns the current bounded summary with wait.timedOut: true when
the timeout expires. The default follows roundTimeoutSeconds + 30.
Acceptance evidence must describe checks actually performed by the delegating party, not a restatement of the worker’s claim.
4. Fan out read-only research
Use a research batch when one delegating Agent needs several articles, web pages, or repositories examined in parallel. Every shard gets its own scratch workspace, so shards can run concurrently without writing into the source project or into each other’s files.
research.json:
{
"title": "Compare candidate projects",
"question": "Which project is the better fit, and why?",
"commonPrompt": "Cite sources and state uncertainty.",
"shards": [
{
"id": "alpha",
"subject": "Analyze Project Alpha",
"url": "https://github.com/example/alpha",
"focus": "architecture and license"
},
{
"id": "beta",
"subject": "Analyze Project Beta",
"url": "https://github.com/example/beta",
"focus": "maintenance and test coverage"
}
]
}waxwing research-start @research.json
waxwing research-wait research-xxxxxxxxxxxx
waxwing research-status research-xxxxxxxxxxxx
waxwing research-collect research-xxxxxxxxxxxxresearch-wait waits for the whole batch in one call and also accepts
--timeout. Waxwing closes successful shard runtimes automatically and keeps partial
results when another shard fails. research-collect writes an aggregate report
under <WAXWING_HOME>/reports; pagination uses --offset and --limit.
Scratch workspaces default to <WAXWING_HOME>-research and can be moved with
WAXWING_RESEARCH_ROOT.
Research batches are for reading and synthesis. Multiple execution Agents must
not write concurrently in the same physical project directory. For write work,
use one task per isolated worktree or serialize changes through shared.
MCP
Configure your MCP client to run:
waxwing-mcpPublic tools use the waxwing_* prefix. The complete ds_* catalogue remains
available as a compatibility alias.
Core tools include create, list, status, wait, rework, accept, cancel,
close, cleanup_worktree, export, preview_delete, and delete. Research
fan-out uses waxwing_research_start, waxwing_research_status,
waxwing_research_wait, waxwing_research_collect, and
waxwing_research_cancel.
Desktop
Development:
cd desktop
npm ci
npm run tauri devBuild a Windows portable release from the repository root:
npm run desktop:portableThe Windows portable archive includes the desktop executable, backend
resources, a Node runtime, license, and unsigned-build notice. It is not code
signed; verify SHA256SUMS and expect possible SmartScreen warnings.
Runtime protocol
run → ack → events/heartbeat → result|error → releasedA result is not a release. Rework and provider fallback wait until the previous
round is explicitly released. A busy worker returns worker_busy; it never
silently drops a run. Every round message carries a roundId, and every task
event has a monotonic sequence.
Workers heartbeat every five seconds. Twenty seconds without a heartbeat marks the runtime unhealthy but does not kill it. On manager restart, Waxwing only terminates a residual process when PID, task ID, owner marker, and command line all match. Otherwise it keeps the workspace lock and reports manual action.
See docs/architecture.md for the full flow.
Data and migration
Default data roots:
Windows:
%LOCALAPPDATA%\WaxwingmacOS:
~/Library/Application Support/WaxwingLinux:
$XDG_DATA_HOME/waxwingor~/.local/share/waxwing
WAXWING_HOME overrides the root. On first start, repository-local legacy data
is copied into the new root; the old directory is retained. Migration never
overwrites a non-empty target.
Task directories contain local state and must not be used as worker workspaces. Deleting task scratch data requires a separate interactive human authorization; project files and the external report are preserved.
Configuration
Configuration layering:
prototype/config.jsonorWAXWING_CONFIGThe local override:
WAXWING_LOCAL_CONFIG, then<platform data directory>/config.local.json, then the legacyprototype/config.local.jsonwhen the new file does not existenvironment variables
A relative path in the local override resolves against the directory that
contains that file; a relative path in config.json resolves against the
config.json directory. The desktop settings page writes to the new location,
converting any relative paths inherited from a legacy file to absolute paths
so they keep pointing at the same directories. The legacy file is left in
place.
Common environment variables:
Variable | Purpose |
| Per-user data root |
| Parent directory for per-shard research workspaces |
| Main configuration file |
| Local override file |
| Node executable for workers |
| DeepSeek Harness checkout |
| DSH credential store |
| Provider JSON directory |
| Loopback manager port, default |
| Packaged/custom backend root for the desktop app |
DSH_SUBAGENT_* and DSH_PROTOTYPE_* remain supported compatibility aliases
during 0.1.x.
Security model
Manager binds to
127.0.0.1and requires a random bearer token.Browser origins are rejected.
Worker credentials are read from the environment/credential store, not copied into arguments or task JSON.
Workspaces overlapping the managed data root are refused.
Only owned, identity-matched runtime processes may be terminated.
The trust boundary is the local operating-system account. Waxwing cannot distinguish a human from another program running as that user.
Report vulnerabilities through GitHub Private Vulnerability Reporting as described in SECURITY.md.
Development
npm test
npm run desktop:build
cargo fmt --manifest-path desktop/src-tauri/Cargo.toml -- --check
cargo check --locked --manifest-path desktop/src-tauri/Cargo.tomlCore tests do not need real model credentials. Real provider checks consume quota and are intentionally excluded from CI.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.
Read a project's prompts, logs and agents, and send new work to the agent on your own machines.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables an AI agent to run local tools on the user's own machine via stdio, including command execution, workspace file read/write, and system status checks.52MIT
- FlicenseBqualityBmaintenanceEnables local, stdio-based task dispatch from Codex to DeepSeek Harness with independent review, bounded rework, persistent queues, and completion tracking.15-
- AlicenseAqualityBmaintenanceA task-level STDIO MCP server that lets Codex or any other MCP client hand off scoped coding jobs to an asynchronous worker agent which reads the code, edits files, and runs tests, while the client keeps ownership of planning and acceptance. Exposes submit, wait, query, follow-up, and cancel tools so multiple clients can queue and monitor tasks against a chosen project root.51MIT
- AlicenseNot gradedqualityFmaintenanceEnables a primary coding agent to delegate bounded implementation and repair tasks to a local OpenAI-compatible model that edits a copy of the project, runs configured checks, and returns artifacts for review. Exposes stdio tools for capability discovery, task submission, progress polling, artifact reading, and cancellation.MIT