wiff

wiff

ハーネスに依存しない、決定論的で再開可能なマルチエージェントワークフロー — プレーンな JavaScript で記述できます。wf のようで、wiff です。

祈る代わりに、小さなスクリプトでタスクをエージェントの群れに振り分けましょう。agent()、/goal ステージ、parallel()、pipeline() を使って通常の JavaScript を記述すると、ランタイムがバックグラウンドで実行し、すべてのステップをジャーナルに記録します。そして実行が途中で停止しても、完了済みのエージェントに一度も再課金することなく再開できます。一時的な MCP ブリッジが永続的なローカルデーモンと通信するため、実行中のワークフローは、それを起動した Codex、Claude Code、Cursor、cron プロセスが終了しても動作し続けます。一方、各子エージェントは Codex、Claude、Cursor、Kimi 上で実行されます。

export const meta = {
  name: "audit",
  description: "Audit files in parallel, fix confirmed issues in isolation",
  phases: [{ title: "Audit" }, { title: "Fix" }],
};

phase("Audit");
const findings = await parallel(
  args.files.map((file) => () =>
    agent(`Audit ${file} for auth bugs`, {
      key: `audit:${file}`,          // stable key → free replay on resume
      sandbox: "read-only",
      schema: findingSchema,          // structured JSON output
    }),
  ),
);

phase("Fix");
return await parallel(
  findings.filter((f) => f.real).map((f) => () =>
    agent(`Fix: ${f.summary}`, {
      key: `fix:${f.file}`,
      agentType: "surgeon",           // persona from .codex/agents/surgeon.md
      isolation: "worktree",          // own git worktree — parallel writes can't collide
      sandbox: "workspace-write",
    }),
  ),
);

条件が本当に満たされるまでステージを動作させ続ける必要がある場合は、ネイティブの Codex ゴールを作成します。

phase("Verify and repair");
await agent("/goal Make the unit tests pass and verify the final run.", {
  key: "tests-green",
  sandbox: "workspace-write",
  timeoutMs: 30 * 60 * 1_000,
});

Wiff はその記述の箇所でワークフローを保持し、ゴールが有効な間、同じ Codex スレッドを継続します。次のステージは、ワーカーがゴールの完了をマークしてから開始します。ブロック中、一時停止中、または制限されたゴールは、明示的に失敗します。

永続的な設定は ~/.wiff/config.json に保存し、必要に応じてプロジェクトごとの設定を <cwd>/.wiff/config.json に追加します。

{
  "version": 1,
  "instructions": "Verify before reporting success.",
  "defaults": {
    "model": "claude-sonnet-5",
    "fallbackModels": ["gpt-5.6-sol"]
  },
  "rules": [
    {
      "name": "fix-until-green",
      "when": { "phase": ["Fix", "Repair"] },
      "goal": "Relevant tests must pass.",
      "options": {
        "model": "gpt-5.6-sol",
        "effort": "high"
      }
    }
  ]
}

デフォルト値は、エージェントオプションの不足分を補います。一致ルールは明示的なユーザーポリシーであり、生成されたワークフローのオプションより優先されます。指示はタスクとともに注入され、優先順位付きのフォールバックモデルはバックエンドをまたいで利用できます。また、該当する設定の変更により、再開時にキャッシュ済みの結果が無効になります。

理由

ハーネスに依存しないワークフローオーケストレーションシステムは存在しません。 どのコーディングハーネスにも、何らかのマルチエージェント機能があります。Claude Code には Workflow ツール、Codex にはサブエージェント、Cursor には独自のエージェントがあります。しかし、どれも各ハーネスに強く結び付いています。実行はそのアプリとともに始まり、アプリを閉じれば終わります。状態はほかのツールから見えず、それぞれのチャットウィンドウ以外から操作することもできません。wiff はオーケストレーションをハーネスから切り離します。永続的なローカルデーモンが実行と耐久性のあるディスク上の状態を管理し、各ハーネスには使い捨ての stdio MCP ブリッジが用意されます。Codex、Claude Code、Cursor、cron ジョブなど、あらゆる MCP クライアントから、同じ実行を開始、切断、監視、再開、キャンセルできます。オーケストレーション自体は会話ではなくスクリプトです。

アドホックなマルチエージェントオーケストレーション（「この作業のためにサブエージェントを何人か起動する」）も、実行が40エージェントにまで膨らみ、何かが停止するまではうまくいきます。コードとして定義するワークフローには、次の利点があります。

• 決定性 — オーケストレーションは雰囲気ではなくスクリプトです。ワークフローコード内で時間、乱数、ファイルシステム、ネットワークを使わず、エージェントが外部の作業を担います。

• 親より長く存続 — 起動元の MCP ブリッジを閉じたり終了させたりしても、実行は中断されません。切り離されたデーモンが実行を続け、別のハーネスから実行 ID を使って再接続できます。

• 再試行ではなく再開 — エージェント呼び出しはすべて、安定したキーと入力ハッシュとともにジャーナルに記録されます。デーモンを正常に再起動すると、耐久性のあるアクティブな実行は自動的に再開されます。デーモンまたはマシンが突然クラッシュした場合は、安全に中断された実行を明示的に再開してください。変更のない完了済みエージェントはキャッシュから即座に、無料で再生されます。ターンの途中で中断されたエージェントは、前回の試行のトランスクリプトのダイジェスト（「ここまでに行った作業を引き継いで続けてください」）を注入して再実行されます。また、ワークツリーエージェントは最初からやり直さず、途中までのチェックアウトを引き継ぎます。

  

  このスクリーンショットが示すのが、この機能です。合成の途中でホストが終了しましたが、再開すると完了済みの4つのエージェントはジャーナルから0msで復元され、中断されたエージェントだけが再実行されました。

• 失敗時に停止するセマンティクス — エージェントが拒否すると、ワークフローはその失敗を明確に示して失敗します（明示的なオプトアウトは parallelSettled() です）。成功を装う、何も通知しない null はありません。

• 可視性のあるスケジューリング — エージェントは、ランタイムのスロットを取得する前にキュー待ちとしてジャーナルに記録され、バックエンドでの実行が始まった時点でのみ実行中になります。キュー待ち時間と実行時間は別々に記録され、オーナーのハートビートにより、稼働中ながら停止しているワークフローも確認できます。

• 必要な箇所での分離 — isolation: "worktree" を指定すると、書き込みを行う各エージェントに新しい切り離された git worktree が与えられます。変更のないものは削除され、変更のあるものは保持され、確認またはマージできるよう実行に一覧表示されます。

• ペルソナ — agentType: "reviewer" を指定すると、Markdown のペルソナが子エージェントの開発者向け指示として注入されます。フロントマターでモデル、処理強度、サンドボックスのデフォルト値を設定できます。

インストール

Codex（プラグイン：MCP ツールと $workflow 作成スキル）：

codex plugin marketplace add https://github.com/xxxoooxoxo/wiff.git
codex plugin add wiff@wiff

Claude Code（プラグイン：MCP ツールとスキル）：

claude plugin marketplace add xxxoooxoxo/wiff
claude plugin install wiff@wiff

その他すべて — サーバーは npm (@xxxoooxoxo/wiff) と公式 MCP Registry（io.github.xxxoooxoxo/wiff）に登録されています。そのため、レジストリに対応したクライアントは名前を指定してインストールでき、それ以外では npx を使って実行できます。

npx -y @xxxoooxoxo/wiff        # stdio MCP server

またはローカルのチェックアウトから：

git clone https://github.com/xxxoooxoxo/wiff.git
codex plugin marketplace add ./wiff
codex plugin add wiff@wiff

次に、新しい Codex セッションを開始し、同梱のスキルを $workflow で呼び出すか、「再開可能なワークフローとして実行して」と尋ねてください。

プラグインをインストールすると、5つのワークフローコントローラーツールが自動承認されるため、ヘッドレス実行でもデスクトップ実行でも MCP の承認プロンプトで止まりません。エージェントのファイルシステムアクセスは、引き続き呼び出しごとに sandbox で制御されます。

他のハーネス（Claude Code、Cursor、任意の MCP クライアント）からの使用

Codex プラグインはパッケージングにすぎません。その基盤となるエンジンは通常の stdio MCP サーバーなので、MCP を扱えるハーネスであればどれでも wiff ワークフローをオーケストレーションできます。基本的な考え方は、オーケストレーターもワーカーも差し替え可能ということです。どの環境で実行する場合も、各 agent() 子プロセスはモデル名に応じてバックエンドを選択します。gpt-*／o* モデルは、ローカルの codex app-server を使うネイティブの Codex スレッドとして実行されます（gpt-6-astra には Codex CLI >= 0.153.4 が必要です）。現行の claude-fable-5-1、claude-fable-5、claude-opus-5、claude-sonnet-5、claude-haiku-4-5 モデルと、変動する fable／opus／sonnet／haiku エイリアスは、ヘッドレスの claude エージェントとして実行されます。composer-* および grok-* モデル（cursor-grok-* スラッグを含む）は、公式 Cursor SDK（@cursor/sdk）をインプロセスで通じて実行され、kimi-code/* モデルはヘッドレスの kimi プロセスとして実行されます。ワークフローではこれらを自由に組み合わせられます（provider: "codex" | "claude" | "cursor" | "kimi" で推論結果を上書きでき、認識されないモデルのフォールバックは WIFF_BACKEND で設定します）。Claude、Cursor、Kimi のバックエンドでは、workspace-write に isolation: "worktree" が必要です。Kimi の read-only モードは、プリントモードではツールが自動承認され、OS サンドボックスもないため、あくまで推奨設定です。

使用するハーネスにかかわらず、マシンには Node >= 22、isolation: "worktree" を使用する場合は git、そしてエージェントが使用するバックエンドのランタイムが必要です。Codex CLI >= 0.144.6、認証済みの claude CLI、Cursor エージェント用の CURSOR_API_KEY、または要求する完全なモデルエイリアス（例：kimi-code/k3）で設定した kimi CLI が必要です。

Claude Code — 前述のプラグインをインストールするのが簡単です。サーバーだけを手動で接続するには、次のようにします。

claude mcp add wiff -- npx -y @xxxoooxoxo/wiff

ツール呼び出しは Claude Code 独自の権限システムを通ります。呼び出しごとの確認を省略するには、.claude/settings.json で 5 つのツールを許可します。

{ "permissions": { "allow": [
  "mcp__wiff__workflow_start", "mcp__wiff__workflow_status",
  "mcp__wiff__workflow_wait", "mcp__wiff__workflow_cancel",
  "mcp__wiff__workflow_models"
] } }

Cursor／Windsurf／Claude Desktop — サーバーをクライアントの mcp.json に追加します。

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

Codex 以外のホストに関する注意事項：

• 状態は共有されます。 すべてのハーネスは同じ ~/.wiff/runs/ を読み書きするため、Codex から開始した実行を Claude Code から監視、キャンセル、再開できます（逆も同様です）。ライブビューアーにもすべて表示されます。
• 実行はデーモンが管理します。 最初のコントローラー呼び出しで、Wiff の状態ルートごとに切り離されたデーモンが 1 つ起動します。MCP ブリッジが終了しても、実行中の作業には影響しません。デーモンはデフォルトで 15 分間アイドル状態が続くと終了します（WIFF_DAEMON_IDLE_MS で変更できます）。PID、ソケット、ログは ~/.wiff/daemon.json と ~/.wiff/daemon.log に書き込まれます。
• コントローラーは作業を送信する前に認証します。 ~/.wiff/control/ 内のアクセス許可が 0600 に設定されたシークレットを使用して、チャレンジレスポンス方式のハンドシェイクを行います。ブリッジはワークフロースクリプトや引数を送信する前にデーモンの正当性を証明し、デーモンもすべてのコントローラーリクエストを認証します。
• 所有権は古いファイルではなく、OS のリースによって管理されます。 シークレットから導出したループバックポートは、デーモンの稼働中ずっと確保されます。OS がポートを厳密に 1 つの所有者に割り当て、クラッシュ時には自動的に解放します。その所有者だけが制御ソケットやロックメタデータを置き換えられます。導出されたポートが無関係なローカルソフトウェアと競合する場合は、WIFF_DAEMON_OWNERSHIP_PORT に利用可能なループバックポートを設定してください。Wiff はその競合を正確に報告し、稼働中の所有者として扱うことはありません。
• デーモンの環境変数は最初のコントローラーから引き継がれます。 PATH、バックエンドの認証情報、CODEX_HOME、ペルソナのパス、Wiff のデフォルト設定は、デーモンを起動したブリッジのものが使われます。これらが変更された場合は、~/.wiff/daemon.json に記録された PID を正常に終了させるか（次のブリッジ起動時に、永続化された実行が再開されます）、15 分間のアイドル終了を待ってください。
• スクリプトの仕様をコンテキストに含めてください。 $workflow スキルは Codex 内でのみ自動読み込みされます。他のハーネスでは、モデルが有効なスクリプトを作成できるように、plugins/wiff/skills/workflow/references/api.md を参照させてください（または、スキルをハーネスのスキル／ルールディレクトリにコピーしてください。例：.claude/skills/ や Cursor のルール）。
• ペルソナは、すべてのハーネスで毎回 <cwd>/.codex/agents/、次に ~/.codex/agents/ から解決されます。別の場所を使うには、サーバーの環境変数に CODEX_WORKFLOW_AGENTS_DIR を設定してください（例：共有の ~/.claude/agents）。
• workflow_start では絶対パスの cwd を明示する必要があるため、サーバー自体の作業ディレクトリは結果に影響しません。

エージェント向け

コーディングエージェントとして MCP 経由で wiff を操作する場合、またはこのリポジトリで作業する場合は、AGENTS.md をお読みください。5 つのワークフローツール、エージェントがつまずきやすいスクリプト作成ルール（安定した key、プロミスではなくサンク、ワークフローコード内での I/O の禁止、並行して書き込む場合のワークツリー分離）、実行状態の保存場所、ランタイムの変更を検証する方法について説明しています。スクリプトの仕様全体はAPI リファレンスに記載されています。

仕組み

このプラグインは、stdio MCP ブリッジを通じて workflow_start、workflow_status、workflow_wait、workflow_cancel、workflow_models の5つのツールを公開します。ブリッジは、認証済みのローカルソケットを介して、必要に応じて起動するデタッチされたデーモンに接続します。ワークフローマネージャー、バックエンド、ハートビート、ジャーナルはデーモンが管理するため、ブリッジを閉じても実行中の処理は停止しません。シークレットから導出されたループバックリースにより、プロセス1つだけがそのライフタイム全体にわたってOSレベルの所有権を持ちます。ソケットとロックのメタデータを置き換えられるのは、その所有者だけです。チャレンジレスポンス方式のハンドシェイクにより、スクリプトや引数が接続を通過する前にデーモンの身元を証明します。開始されたワークフローは、ロックダウンされた Node vm 内でスクリプトを実行します（インポート、ファイルシステム、シェル、ネットワーク、時刻、乱数は使用できず、いずれも例外をスローします）。各 agent() 呼び出しは、モデル名または明示的な provider に基づいて Codex、Claude、Cursor、Kimi のいずれかのバックエンドにルーティングされます。子の内部では再帰的なオーケストレーションが無効になっています。

実行に関するすべての情報は ~/.wiff/runs/<runId>/ に永続化されます。

run.json         status, phase, counters, failures, kept worktrees
script.js        the exact source (reread on resume)
journal.jsonl    every phase/log/agent event, with input hashes and token usage
agents/*.jsonl   full per-child transcripts
worktrees/       isolated checkouts for agents that asked for them

起動元のホストが停止しても、ステータスの確認、待機、キャンセルが可能です。デーモンを正常に再起動すると、実行中の永続化された実行は自動的に再開されます。デーモンが突然クラッシュした場合は、重複した副作用のリスクを避けるため、次のデーモンはその実行を interrupted とマークします。どのクライアントからでも、ジャーナルから再開できます。

スクリプトの仕様全体についてはAPI リファレンスを、段階的な例についてはexamples/verify-and-fix.jsをご覧ください。

ライブビューアー

ローカルのウェブ UI で、すべての実行と、その中のすべてのエージェントを監視できます。

npx -p @xxxoooxoxo/wiff wiff-viewer    # http://127.0.0.1:4979  (--port / --root to override)
# or from a checkout: cd plugins/wiff && npm run viewer

依存関係はゼロで、実行ファイルを読み取り専用で参照するため、どのプロセスが所有する実行でも監視できます。画面上部のライブストリップには、すべての実行でキュー待ちまたは実行中のエージェントがすべて表示されます。キュー待ち時間に加え、実行中のエージェントが現在行っていること（トランスクリプトから取得した最新のコマンド、ファイル編集、または思考内容）も表示されます。所有者のハートビートにより、ホストの停止を検出できます。その下には、フェーズごとのエージェントカード、ライブステータス行、ガントチャートのタイムライン、トークン数、保持されたワークツリー、クリックして開けるライブ追跡トランスクリプトドロワーがあります。ゴールノードは、キュー待ち、アクティブ、達成、失敗、再生済みの状態で表示されます。ライトテーマとダークテーマに対応しています。

関連プロジェクト

• robzilla1738/Codex-Workflows — レビューファンアウトに特化した、Codex 向けワークフロー・アズ・コードのランタイムです。設計は収束していますが、実装は独立しています。
• scasella/claude-dynamic-workflows-codex — Claude Code の dynamic-workflows DSL を GPT エージェント向けに再ホストしたもので、セッションを維持するワーカーとブラウザー実行ビューアーを備えています。
• Codex のネイティブサブエージェント — 対話的な人間の監督下でファンアウトを行うのに最適です。このプラグインは、自動化され、再開可能で、ジャーナルに記録されるファンアウト向けです。

開発

cd plugins/wiff
npm test        # unit tests (fake backend, no tokens spent)
npm run check   # syntax check
npm run smoke   # one real Codex child, end to end

完了したスモーク実行の ID を渡すと、モデルを再度呼び出さずに、プロセスをまたいだ再開を検証できます。

npm run smoke -- wf_<run-id>

Codex はインストール済みプラグインをバージョン管理されたキャッシュから実行します。ソースを編集した後は、.codex-plugin/plugin.json のバージョンを上げてから codex plugin add wiff@wiff を再実行し、変更を反映してください。

リリース

mainへのバージョン変更のマージにより、パッケージがnpmに自動で公開され、その後、同じバージョンがMCP Registryに登録されます。次のファイルでバージョンを揃えてください。

• plugins/wiff/package.json
• plugins/wiff/.codex-plugin/plugin.json
• plugins/wiff/.claude-plugin/plugin.json
• server.jsonとそのnpmパッケージエントリ

これらの値、またはnpm/MCPのパッケージ名が一致しない場合、リリースワークフローは公開前に失敗します。再実行しても問題ありません。いずれかのレジストリにすでに存在するバージョンはスキップされます。

npmへの公開には、長期間有効なトークンではなく、信頼されたGitHub Actionsパブリッシャーを使用します。@xxxoooxoxo/wiffのnpmにおける初回設定は、リポジトリがxxxoooxoxo/wiff、ワークフローがrelease.ymlで、npm publishが許可されている必要があります。MCP RegistryもGitHub OIDCで認証するため、リポジトリシークレットは不要です。

ライセンス

MIT