Wakeflow

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:

 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)

/
  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:

/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:

npx codex-marketplace add GxFn/Wakeflow/plugins/codex-wakeflow --plugin

For a pinned release after the matching tag exists:

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:

[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.

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:

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.

1. For a clean workspace, Codex calls the tool again with explicit

repositories mappings for the intended work windows.

1. For a messy workspace, Codex asks which directories are managed windows

before writing. It must not use a broad discovered-directory import.

1. After user confirmation for a fresh workspace, Codex calls

wakeflow_initialize_workspace with apply: true.

1. 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).

1. 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.

1. 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
• Source: GxFn/Wakeflow
• License: MIT
• Homepage: https://github.com/GxFn/Wakeflow#readme

Install and usage instructions live in the source repository linked above.