# Wakeflow > Dual-host Wakeflow plugins for Codex and Claude Code: controller state roots, task packages, direct-thread/session delivery, evidence review, and local-first runtime. - **Type:** MCP server - **Install:** `agentstack add mcp-gxfn-wakeflow` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [GxFn](https://agentstack.voostack.com/s/gxfn) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [GxFn](https://github.com/GxFn) - **Source:** https://github.com/GxFn/Wakeflow - **Website:** https://github.com/GxFn/Wakeflow#readme ## Install ```sh agentstack add mcp-gxfn-wakeflow ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Wakeflow A disciplined control loop for multi-window agent work — every step traced, every result proven. [English](README.md) | [Simplified Chinese](README.zh-CN.md) Wakeflow turns a local Codex or Claude Code workspace into a disciplined controller system: a controller-owned loop for each active demand, focused repository windows, explicit state roots, compact direct-thread or direct-session delivery, and evidence-based acceptance. The controller runs this as a closed loop — plan, dispatch, collect evidence, review, decide, repeat — and records every step, so the whole run is auditable after the fact. --- - [Why Wakeflow](#why-wakeflow) - [Architecture](#architecture) - [Install Wakeflow](#install-wakeflow) - [Initialize A Workspace](#initialize-a-workspace) - [Run Your First Demand](#run-your-first-demand) - [What Wakeflow Creates](#what-wakeflow-creates) - [Automation Semantics](#automation-semantics) - [MCP Capability Surface](#mcp-capability-surface) - [Runtime And Ledger Boundaries](#runtime-and-ledger-boundaries) - [Dual-Host Workspaces](#dual-host-workspaces) - [Marketplace Release](#marketplace-release) - [Working In This Repository](#working-in-this-repository) - [Design Principles](#design-principles) ## Why Wakeflow Hand an agent fleet a real, multi-repository goal and come back later with the three questions that matter: **what was actually done, what evidence proves it, and what is still open?** Without a control layer the honest answer is a pile of scattered prompts, copied status tables, unclear ownership, and "looks done" — work that cannot be audited, resumed, or trusted. Wakeflow is that missing control layer — one controller window drives focused repository windows through an explicit, machine-checked loop, and every step leaves a verifiable artifact on disk: - **Controller-first judgment**: the parent workspace owns goals, boundaries, dispatch decisions, acceptance, TODO routing, and archive decisions. - **One state root per demand**: task packages, target results, review candidates, decisions, and progress projections stay tied to the same demand. - **Focused child windows**: each repository window works only inside its configured responsibility boundary. - **Compact delivery**: direct-thread prompts wake the right window with a small envelope; the state root and skills hold the task details. - **Evidence before acceptance**: target backfill is input, not a conclusion. The controller still reviews raw evidence before completing work. - **Local-first runtime**: real thread ids live only in the local thread registry; window config is a derived sendability view, and active state stays out of tracked source. What you get, concretely: - **Auditable** — every dispatch, delivery, result, and decision is a JSON artifact tied into one trace spine; `wakeflow_view` (scope `trace`) replays who did what, on which evidence, at which state revision. - **Resumable** — demands continue from their on-disk state roots. Codex threads and Claude Code conversations are rebound from host-local registered ids; after a machine reboot, Claude's tmux windows must be relaunched before those conversations resume. No conversation memory is state authority. - **Hard to fake** — acceptance requires raw evidence that the reducers verify on disk (missing evidence refs fail closed); "the target said done" is never enough, and results never accept themselves. - **Parallel without chaos** — up to `maxActiveDemands` demands run side by side as isolated pods (own controller, own worktrees, own Test); within one demand each repo stays strictly one-window-one-package, and pod branches merge back only through a human-reviewed ledger. - **Safe by construction** — fail-closed guards on ownership, capacity, locks, and archive redaction; real session ids never leave the local registry. Wakeflow is not a command launcher with nicer names. It is a reusable workflow capability for keeping multi-window agent work legible, bounded, and resumable. ## Architecture Wakeflow is three layers working together: a window fleet you can see, a closed loop that moves the work, and a disk layout that survives restarts. Both editions — Codex and Claude Code — run the same host-neutral state, delivery, and validation core. Their manifests, memory files, window lifecycle, and transport remain host-specific (Codex host thread tools vs a tmux helper). ### Layer 1 — the fleet (what you see) Every Wakeflow window is an agent session pinned to one responsibility. On Claude Code the baseline fleet lives in the configured tmux session and each demand pod has its own tmux session; on Codex the windows are host threads. | Window | Role | Default reasoning effort (Claude Code) | | --- | --- | --- | | Controller | owns goals, dispatch, evidence review, acceptance | `max` | | Design | clarifies requirements, redesigns non-bug outcome mismatches, prepares handoffs | `xhigh` | | Repo windows | implement inside exactly one repository | `xhigh` | | Test | after controller validation, explores only the approved real-environment boundary for hidden bugs | `xhigh` | ### Layer 2 — the loop (how work moves) Work is organized into demands: one demand = one goal = one state root on disk. Every demand moves through the same closed loop: ```text 1 init raw state init creates the demand root (unclaimed) 2 claim public create, or first raw-state drive, binds host (codex | claude) 3 add task a task package names the target window and scope 4 dispatch envelope written -> window LOCKED -> prompt delivered 5 work the target window executes inside its repository boundary 6 result TargetResultEnvelope lands with evidence refs -> lock released 7 review controller reads RAW evidence, then accepts / reworks / blocks 8 complete only when every task is accepted and no blockers remain ``` Two rules keep the loop honest: **prompts wake, state instructs** (the delivered prompt only names window, task id, and state root; the task definition lives in the state root and skills), and **backfill is input, not acceptance** (the controller reviews raw evidence before any decision; a blocked decision is always recoverable once new evidence arrives). ### Layer 3 — the ground (what's on disk) ```text / wakeflow.config.json windows, roles, per-host knobs committed AGENTS.md / CLAUDE.md per-host controller gates committed wakeflow-ledger/ durable designs, records, archives committed .wakeflow-active/ demand state roots (layer 2) local .wakeflow-local/wakeflow-delivery/ local dispatch-packets/ delivery-envelopes/ delivery-runs/ transport records target-results/ evidence envelopes locks/ one in-flight delivery per window, cross-host hosts/codex/ codex thread registry (host-scoped) hosts/claude-code/ claude session registry + tmux bindings ``` Rule of thumb: **business truth is host-neutral and shared; transport handles are host-scoped and never leave `.wakeflow-local/`.** ### Who decides what (trust model) Scripts and MCP tools create, validate, and record machine data; they never choose acceptance, widen scope, or decide product behavior on their own. They only persist an explicit controller decision. Target windows execute exactly their dispatched package. The controller is the only acceptance authority and must establish functional correctness before Test starts. Test cannot invent goals, methods, or completion criteria; it only investigates the approved environment boundary. The user owns product decisions. ### Dual-host coexistence One workspace may run both editions side by side: demands bind to one platform at claim time (machine-enforced on every driving command), the shared per-window lock serializes deliveries across hosts, and ownership moves only through the explicit, audited `adopt-demand-host` transfer. ## Install Wakeflow Wakeflow uses the same two-layer marketplace shape as Lark Remote: the repository root is the development workspace, and the installable plugin artifacts live under `plugins/`. The repository ships two host editions built from one shared core: | Host | Artifact | Catalog | | --- | --- | --- | | Codex | `plugins/codex-wakeflow/` | `.agents/plugins/marketplace.json` | | Claude Code | `plugins/claude-code-wakeflow/` | `.claude-plugin/marketplace.json` | Install the Claude Code edition from inside Claude Code: ```text /plugin marketplace add GxFn/Wakeflow /plugin install wakeflow@gxfn ``` The Claude Code edition is terminal-only: every Wakeflow window (controller included) is a tmux-resident interactive `claude` session in the `wakeflow` tmux server session, and a Wakeflow thread id is the window's Claude Code session id (stable across resumes). Up to `maxActiveDemands` (default 2) demands may run side by side as **demand pods** — each pod is its own tmux session with its own controller, per-repo isolation worktree windows, and its own Test, the WHOLE pod sharing the demand's one worktree set (Test verifies there, never on a main checkout); claiming past capacity fails closed, and pod branches merge back only through the human-reviewed `pending-merges.md` ledger. See [plugins/claude-code-wakeflow/README.md](plugins/claude-code-wakeflow/README.md) for the full Claude Code guide. Install the public Codex plugin artifact: ```bash npx codex-marketplace add GxFn/Wakeflow/plugins/codex-wakeflow --plugin ``` For a pinned release after the matching tag exists: ```bash npx codex-marketplace add https://github.com/GxFn/Wakeflow/tree/v0.8.13/plugins/codex-wakeflow --plugin ``` If the Codex dialog separates source, ref, and sparse path, use the repository URL, the desired ref, and `plugins/codex-wakeflow` as the sparse path. The Codex edition runs the shared demand-pod model as per-demand thread sets: `wakeflow_pod_open` creates the demand's worktree set and returns a windowPlan the agent realizes with `create_thread` (each thread's cwd is its worktree), and `wakeflow_pod_close` tears it down onto the pending-merges ledger after completion. The invariant is shared (one controller, one Test, and one worktree per selected repository for the demand), while each host owns its window lifecycle and teardown sequence. For local development, register this checkout as its own local marketplace: ```toml [marketplaces.gxfn] source_type = "local" source = "/absolute/path/to/Wakeflow" [plugins."wakeflow@gxfn"] enabled = true [plugins."wakeflow@gxfn".mcp_servers.wakeflow] default_tools_approval_mode = "approve" ``` Wakeflow does not require an aggregate marketplace repository. A separate catalog can still list Wakeflow for brand discovery, but that is not part of the primary install or release path. ## Initialize A Workspace Wakeflow is installed as a Codex or Claude Code plugin. A target workspace does not need to contain Wakeflow source code. The expected target shape is: > Naming: `wakeflow.config.json` is the canonical config name. A pre-rename > workspace's `workspace.config.json` keeps working (read fallback); rename it > with `git mv workspace.config.json wakeflow.config.json` when convenient — > `check-workspace` reminds you. ```text MyWorkspace/ AGENTS.md or CLAUDE.md wakeflow.config.json .wakeflow-active/ # ignored active controller state .wakeflow-local/ # ignored thread registry and derived runtime wakeflow-ledger/ # durable project coordination records ProductRepo/ CoreRepo/ Design/ # default internal requirement-design surface Test/ # default internal test coordination surface ``` The simplest user prompt is: ```text Use Wakeflow to initialize the current workspace. Preview the plan first and wait for my confirmation before writing. ``` The operating flow is: 1. Codex calls `wakeflow_initialize_workspace` with `apply: false`. 2. Wakeflow returns directory facts and an `agentSelectionProtocol`. 3. Codex judges whether the workspace is clean or messy from those facts and user context. 4. For a clean workspace, Codex calls the tool again with explicit `repositories` mappings for the intended work windows. 5. For a messy workspace, Codex asks which directories are managed windows before writing. It must not use a broad discovered-directory import. 6. After user confirmation for a fresh workspace, Codex calls `wakeflow_initialize_workspace` with `apply: true`. 7. Codex creates the returned Codex threads, resets each thread title to the returned `displayTitle`, and passes each real thread id once to Wakeflow's local registration command. The thread registry is the only thread-id authority; window config is refreshed as a derived view. For an already initialized workspace, `wakeflow_initialize_workspace` is not a general refresh button. It may write only after the user explicitly requests a reset initialization; the apply call must set `resetInitialization: true`, pass explicit `repositories`, reconfirm Design/Test mode, and must not use `useDiscovered`. Heavy or stale windows use the replacement commands instead. Command responsibilities stay separate: | Need | Command | Responsibility | | --- | --- | --- | | First-time setup | `wakeflow_initialize_workspace` | Discover, confirm, write workspace config/docs/support surfaces, and return the full launch plan. | | Explicit reset setup | `wakeflow_initialize_workspace` with `resetInitialization: true` | Reconfirm work directories, clean stale managed window cards/runtime for removed windows, and rewrite setup surfaces. | | One heavy/stale window | `wakeflow_replace_windows` (pass `window`) | Return one replacement launch entry and local registration command; no workspace docs refresh. | | Several heavy/stale windows | `wakeflow_replace_windows` | Return only the requested replacement entries and local registration commands; no unrelated window rewrites. | In the Claude Code edition, the same preview/apply contract is used. The returned launch plan is materialized by the tmux host helper instead of Codex `create_thread`: each window is launched as an interactive `claude` session, and the returned Claude Code session id is registered as the Wakeflow thread id. Design and Test are fresh support surfaces by default. Existing similarly named directories such as `Design` or `Test` are treated as ordinary directory facts unless the user explicitly maps them as Design/Test. Wakeflow supports localized initialization. Pass `language: "zh"` for Chinese workspaces, `language: "en"` for English workspaces, or `language: "auto"` when there is no clear preference. Generated thread titles keep the window name at the front so the important repository name remains visible in narrow sidebars. New state-root progress documents and subsequent Unified Status renders also use the selected interface language. Controller and child windows can use Codex or Claude Code subagents to speed up bounded code search, log triage, test localization, and evidence summaries. Subagent output is evidence or advice only; controller review, dispatch, state writes, and repository boundaries remain with the Wakeflow window that owns the task. ## Run Your First Demand The loop is the same on both hosts; only how you drive it differs. **Claude Code (slash commands):** 1. `/wakeflow:init` — discover the workspace, confirm scope with you, write config/docs, and launch the tmux fleet (`tmux attach -t wakeflow` to watch). 2. Feed the goal to the Design window (or write the requirement yourself). Design clarifies it and calls `wakeflow_deliver` — the demand lands as a `pending-claim` row on the global TODO board with its design docs linked. 3. In the controller: `/wakeflow:status` to see … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [GxFn](https://github.com/GxFn) - **Source:** [GxFn/Wakeflow](https://github.com/GxFn/Wakeflow) - **License:** MIT - **Homepage:** https://github.com/GxFn/Wakeflow#readme Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-gxfn-wakeflow - Seller: https://agentstack.voostack.com/s/gxfn - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.