# wiff [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/xxxoooxoxo/wiff  
**GitHub Stars:** 5  
**npm Downloads (last month):** 223  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/wiff

## Description
Deterministic, resumable multi-agent Codex workflows, drivable from any MCP client.

## Tools
Capabilities this server exposes over MCP:

- **workflow_start** — Launch a deterministic JavaScript workflow in the background, or resume a previous run without repeating successful unchanged agent calls. User and project preferences are loaded from Wiff config. Always pass the caller's absolute working directory as cwd.
- **workflow_status** — Read the latest persisted status, phase, counters, result, and artifact paths for a workflow run.
- **workflow_wait** — Wait until a workflow changes state or the timeout elapses. Call repeatedly until the run is completed, failed, cancelled, or interrupted.
- **workflow_cancel** — Interrupt all live agents and mark a workflow run cancelled.
- **workflow_models** — List the models each agent backend (codex, claude, cursor, kimi) can run, with supported reasoning efforts. Backends that are unavailable on this machine report an error instead of models.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "wiff": {
    "command": "npx",
    "args": ["-y","@xxxoooxoxo/wiff"],
    "env": {
      "WIFF_BACKEND": ""
    }
  }
}
```

**Requires environment variables:** `WIFF_BACKEND` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the wiff MCP server does

The wiff MCP server turns multi-agent coding workflows into ordinary JavaScript programs. A workflow can define named phases, invoke `agent()` workers, fan work out with `parallel()`, connect stages with `pipeline()`, and wait on a native Codex `/goal` until its condition is complete. This makes orchestration logic explicit rather than dependent on a particular chat session.

Execution is owned by a persistent local daemon. The MCP bridge used by Codex, Claude Code, Cursor, cron, or another MCP client is disposable, so a client can disconnect while the daemon continues the run. A later client can inspect, resume, or cancel the same run.

## How it works

Each agent call can have a stable key and input hash. Completed calls are recorded in an on-disk journal and can be replayed from cache when a run resumes, avoiding another model call for unchanged work. If an agent was interrupted during a turn, wiff reruns it with a digest of the earlier transcript; worktree-based agents retain their partial checkout.

The scheduler records agents as queued before they receive a runtime slot and as running once backend execution starts. Heartbeats expose workflows that remain alive but stop making progress. Normal failures are propagated instead of converted into empty results; `parallelSettled()` is available when a workflow intentionally wants settled outcomes.

Writing agents can use `isolation: "worktree"` to receive separate detached Git worktrees. Clean worktrees are removed, while dirty ones remain available for inspection or merging. Personas can be selected with `agentType`, which loads a Markdown persona and its defaults from the project’s `.codex/agents` directory.

## Setup and configuration

Node.js 22 or newer is required. Install the npm package with `npx -y @xxxoooxoxo/wiff`, which starts the stdio MCP server. The project also publishes an MCP Registry entry under `io.github.xxxoooxoxo/wiff`. Codex and Claude Code users can install the corresponding repository plugin; the plugin includes MCP tools and a workflow-authoring skill.

Persistent preferences can be stored in `~/.wiff/config.json`, with project-specific overrides in `<cwd>/.wiff/config.json`. Configuration supports instructions, default models, ordered fallback models, and rules that apply options such as model and effort to selected phases. Preference changes that affect a run invalidate relevant cached results on resume.

## Tools and capabilities

The wiff MCP server provides workflow-controller tools for operating runs. Workflow code supports parallel agents, pipelines, structured JSON schemas, phase tracking, goals, model selection, sandbox settings, timeouts, personas, and worktree isolation.

Worker backends are selected from model names or can be overridden with `provider`. Codex models run through a local Codex app-server, Claude models through headless Claude agents, Cursor and Grok models through the Cursor SDK, and Kimi models through headless Kimi processes. `WIFF_BACKEND` provides a fallback for unrecognized model names.

## Limitations and notes

The workflow runtime intentionally excludes time, randomness, filesystem access, and network access from workflow code; agents perform external work. Agent filesystem access is controlled per call through the sandbox setting. A blocked, paused, or limited native goal fails explicitly rather than allowing the next stage to proceed.

The daemon preserves active runs across a graceful restart, but an abrupt daemon or machine crash may require explicitly resuming the interrupted run. Dirty worktrees are retained for manual inspection and merging rather than automatically combined.

_Full upstream README: https://allmcps.com/mcp/wiff/readme_