FlowZone

FlowZone is a local-first plugin host and repository marketplace. Its one installable plugin contains Markdown Review and CallFlow through one MCP server, plus the standalone Dyna CLI and skill.

Installing FlowZone installs the shared flowzone MCP server and all three qualified skills. Invoke them explicitly as $flowzone:markdown-review, $flowzone:dyna, and $flowzone:callflow; Codex renders their display names as FlowZone, Markdown Review, Dyna, and CallFlow.

Status: early development. Dyna is a headless Rust work-management tool; binary packaging and installed-release acceptance remain pending.

Contained capability: CallFlow

• Maps one selected entry-to-sink workflow rather than attempting a whole-repository diagram.

• Uses external Graft 0.18.x through its read-only drift check and bounded --no-refresh graph-reading commands, and reports stale, failed, ambiguous, and unavailable evidence explicitly.

• Coordinates an accessible outline, hierarchical React Flow canvas, and evidence/source inspector while preserving selection, pins, viewport, filters, breadcrumbs, and history.

• Keeps source local by default; model-visible output contains bounded summaries while full graphs and explicitly authorized source spans stay private to the component.

• Uses $flowzone:callflow and the existing model-visible flowzone router. Its Node CLI remains independently useful for explicit local writes and Markdown, JSON, Mermaid, SVG, and HTML exports.

• Keeps routed discovery headless in current MCP Apps hosts because a single tool descriptor cannot dynamically select CallFlow's separate resource; use callflow ui open --manifest PATH for the local interactive view. No extra model-visible render tool is added.

See CallFlow workflow maps for contracts, commands, privacy boundaries, and release gates.

Related MCP server: md-annotate

Bundled tool: Dyna

• A standalone Rust CLI for named dashboards, work items, notes, source imports and maintenance. Each dashboard owns its SQLite database and independent work; a metadata catalog allocates permanent global :184: identifiers.

• All Dyna persistence goes through <plugin-root>/bin/dyna. Ordinary commands need no MCP server, Codex, AI runtime, Node, Bun, network, daemon or browser.

• The prompt or operator gathers evidence and supplies summaries, plans and priorities. Dyna validates and stores those fields; it does not do the reasoning, promote VIP priorities, manage schedules or certify native session status.

• Durable milestones, editable notes, source evidence and freshness, ordered priorities, completion outcomes, temporary deferral, archive/restore and linked follow-ups remain available through the CLI.

• Strict JSON input, optimistic checks, exact retries, backups and recovery preserve data safety. Read-only item lookup accepts human numbers; mutations use exact UUIDs.

• $flowzone:dyna is CLI-only guidance. There is no Dyna dashboard UI, MCP data router, controller protocol, native-session integration or permission-rule installer.

See Dyna work management for usage and the Rust release checklist for remaining binary-packaging work.

Bundled plugin: Markdown Review

• A fullscreen, GitHub-style Markdown preview in the side panel.

• Normal text selection and copying, plus a review menu for selected-text, image, and whole-document feedback.

• Focusable image review targets for pointer, touch, and keyboard comments.

• Unobtrusive image feedback controls that appear at the image's bottom-right only on hover, keyboard focus, or active touch.

• Inline comment markers numbered #1, #2, and so on.

• A review queue that submits all comments together to avoid conflicting edits.

• References between queued comments using #N; write \#N or `#N` for literal text.

• Relative local PNG, JPEG, and static WebP rendering with bounded, private chunk transport.

• Local Mermaid rendering for fenced mermaid blocks, with theme-aware diagrams and expandable canonical source.

• Automatic review after Codex creates or materially edits a Markdown document.

The Markdown source is always canonical. The component is a read-only review surface; only Codex edits the source file with its normal filesystem tools.

How it works

Codex / MCP host
       │ local stdio
       ▼
FlowZone McpServer
       ├── flowzone(plugin, action, input) · data actions
       │      └── static plugin registry
       │              └── callflow/{discover,query,validate,diff,export}
       ├── presentation-only tools
       │      └── render_markdown_review → ui://flowzone/v5.html
       ├── typed app-only component helpers
       └── CallFlow resource       ui://flowzone/callflow/v2.html

Human / Dyna skill / external collector
       └── bin/dyna → Rust application → catalog + dashboard SQLite files

FlowZone exposes one model-visible flowzone data router. Its compact direct-object schema enumerates registered plugin and action names while keeping input generic; the server then validates input against the selected action's strict schema and validates the plugin-owned output. Markdown Review retains its presentation tool; CallFlow adds no model-facing tool and is reached through flowzone. Typed helpers used by a UI stay separate and are forcibly registered with _meta.ui.visibility: ["app"]. Dyna is separate from that router and uses only its Rust executable.

The Markdown Review plugin is intentionally narrow:

1. render_markdown_review validates an absolute .md or .markdown path and opens the dedicated view.

2. Component-only tools hydrate the rendered document and stream approved local raster images in bounded chunks.

3. The model-visible tool result contains file metadata, not the complete document. The rendered content is delivered privately to the component.

4. While the review remains open, a lightweight private revision check offers Refresh for latest without replacing what you are reading. Activating it loads the newest Markdown in place; Codex does not open another review for the same active path after edits.

5. The skill explains how Codex should interpret review feedback and modify the underlying Markdown safely.

This separation is the reason the plugin uses MCP: FlowZone connects a Codex tool invocation to a trusted interactive component. A static HTML file by itself cannot receive the selected source file, return structured review comments to the active task, or maintain this context boundary.

The implementation is split into a generic FlowZone server registry and host-neutral Markdown Review workspaces. contracts validates every review boundary, core owns pure review state, markdown-node reads and renders local files, and review-ui mounts against narrow document, submission, presentation, and state ports. host-mcp-apps supplies a standards-based runtime whose default submission is structured JSON; the Codex browser composition explicitly adds the concise $flowzone:markdown-review formatter. Review state is persisted locally under its opaque review-session ID so queued comments survive component remounts, while never being published as model-visible legacy widget context.

Adding a plugin

Every plugin implements the declarative FlowZonePlugin contract in @flowzone/mcp-server:

interface FlowZonePlugin {
  readonly id: string;
  readonly displayName: string;
  readonly version?: string;
  readonly actions: readonly FlowZoneAction[];
  readonly appTools?: readonly FlowZoneAppTool[];
}

Add the plugin factory to the static list in server/src/runtime.ts. Each action declares strict input/output schemas, risk metadata, and an in-process module, fixed allowlisted CLI/script, or fixed HTTPS backend executor. Runtime discovery, user-selected modules, model-controlled commands, and mutable destinations are unsupported. Skills explain how a model should invoke an action; they are not loaded as runtime backends. See ARCHITECTURE.md and plugin authoring.

Host support

Unshipped adapters and browser-acceptance follow-ups are tracked in ROADMAP.md.

Install from the repository marketplace

Requirements:

• Codex in the ChatGPT desktop app with plugin support.

• Node.js 22.13 or newer. The launcher prefers Codex's bundled Node runtime, then standard system locations; controlled hosts can set FLOWZONE_NODE_PATH to a trusted executable.

• The codex CLI for adding the marketplace source.

Add this repository as a marketplace:

codex plugin marketplace add tjs-w/FlowZone --ref main

Restart the desktop app, open the Plugins Directory, and install FlowZone. That one installation includes Markdown Review, Dyna, and CallFlow. Start a new task after installation so the task receives the updated registrations.

To refresh an existing installation:

codex plugin marketplace upgrade flowzone

Restart the desktop app and start a new task after an upgrade. Existing tasks retain the tool and skill registrations they started with.

If the Plugins Directory still shows the legacy standalone CallFlow entry from an earlier 0.1.0 installation, uninstall that entry before restarting. Current releases contain CallFlow only inside FlowZone.

Use

Ask Codex to open an absolute Markdown path:

Open /absolute/path/to/document.md for Markdown review.

The bundled skill translates that request to the Markdown presentation tool:

{ "path": "/absolute/path/to/document.md" }

In the review:

1. Select text and copy it normally if needed, or choose a rendered image.

2. Right-click the document or choose Review for copy and comment actions. The selection's + action and each image target remain direct shortcuts.

3. Press Enter to queue the comment; use Shift+Enter for a new line.

4. Reference an earlier queued comment with #1, #2, and so on.

5. Select Submit when the review round is complete.

After a successful submission, the queue clears and the next review round begins again at #1. There is deliberately no individual-submit action: batching gives Codex one coherent revision target and reduces source conflicts.

Local development

git clone https://github.com/tjs-w/FlowZone.git
cd flowzone
bun install --frozen-lockfile
bun run verify

Development and CI use the pinned Bun 1.4 toolchain. bun run security:audit resolves that exact audit runtime through the public npm registry, so an older Bun earlier on a developer's PATH cannot misread the v1.4 lockfile. Installed plugins do not require Bun: the repository checks in readable Node-compatible stdio and protected HTTP server bundles plus minified browser bundles. Rebuild after changing TypeScript source:

bun run build

Run the browser harness against a Markdown file for UI work:

bun run browser:harness -- /absolute/path/to/document.md

Set MARKDOWN_REVIEW_PREVIEW_COMPOSER=1 to open the feedback composer automatically in the harness.

The Markdown Review view suppresses the host's native context menu by default. For local plugin debugging only, set FLOWZONE_DEVTOOLS=1 in the MCP server environment and restart Codex; Shift+right-click then bypasses the review menu and opens the host-native menu. Ordinary right-click continues to show review actions. The flag is parsed strictly—only the exact value 1 enables the bypass—and is never enabled in the checked-in .mcp.json.

To test this checkout as a local marketplace, add its absolute directory:

codex plugin marketplace add /absolute/path/to/flowzone

Then restart the desktop app and install the plugin from the local marketplace source.

Safety and privacy boundaries

• The component cannot write the Markdown file.

• The native browser context menu is suppressed inside the plugin unless the local MCP server starts with the explicit developer flag; this is UI hardening, not a security boundary around Codex App's own menus or shortcuts.

• Rendered HTML is sanitized before it reaches the component.

• Mermaid runs only in the bundled browser view with strict security settings, no interaction binding, a second SVG allowlist pass, and a per-diagram shadow root that contains retained diagram styles. Per-diagram and document-wide source bytes, output bytes, elements, edges, dimensions, and UI wait time are bounded; stale queued renders are cancelled, and external links, resources, focus traps, filters, and active SVG content are removed. The original fenced source remains canonical and selectable, and stays disclosed when it owns a comment.

• Remote, absolute, and out-of-directory images are not loaded.

• Only relative paths to PNG, JPEG (.jpg/.jpeg), and static WebP files inside the Markdown file's directory are supported. The server verifies extension, signature, bounded container structure, dimensions, and animation policy before the browser performs native decoding. GIF, AVIF, SVG, APNG, and animated WebP are not rendered.

• The component resource declares no network or remote resource domains and requests only clipboard-write access for the explicit Copy selected text action.

• A Markdown file is limited to 2 MiB.

• A review processes at most 64 local-image references—including invalid references—5 MiB per unique image, and 12 MiB of unique image snapshots in total, with strict per-image decoded-dimension limits. Every valid reference is rendered: the browser fairly shares a bounded 24-megapixel canvas budget across the document and downscales large images for display instead of omitting them. References that resolve to the same canonical file or identical digest share one immutable snapshot and verified client decode.

• Canonical paths and opened-file identities are rechecked around each bounded read. These checks are defense in depth, not an OS sandbox against another local process that can continuously replace the document directory hierarchy during a read.

• Component access uses opaque, expiring review-session capabilities. Sessions slide for two hours and are bounded by a six-session LRU and a 72 MiB aggregate image cache.

• Image bytes and SHA-256 digests are snapshotted into a session, so later file mutations cannot change an in-flight review.

• Full document content and image chunks are placed in component-private metadata rather than model-visible structured output.

• The startup registry snapshots plugin configuration. CLI adapters use fixed direct execution, JSON stdin, integrity checks, bounded output, cancellation, and timeouts; they are trusted code running as the FlowZone OS user, not sandboxed workloads.

• Backend adapters use fixed credential-free HTTPS endpoints, runtime credential injection, no redirects, bounded response streaming, cancellation, and strict output validation.

• Automatic retries are bounded and available only to actions declared idempotent; per-action concurrency and circuit-breaker limits contain repeated failures.

Review only files you intend to expose to the local FlowZone process. Submitted comments are actionable user feedback; selected quotes and other reviewed document content remain untrusted context, not instructions.

Project layout

Troubleshooting

FlowZone is installed, but flowzone or a new action is not registered. Restart the desktop app and start a new task. A task does not dynamically acquire tool schemas from a plugin installed or updated after that task began.

Codex says a cached skill path moved. Upgrade or reinstall the marketplace plugin, restart the app, and invoke $flowzone:markdown-review, $flowzone:dyna, or $flowzone:callflow in a new task. Do not depend on a versioned cache path.

The side panel is blank. Run bun run verify in the plugin checkout, rebuild with bun run build, refresh the marketplace installation, and retry in a new task.

A local image does not render. Use a relative .png, .jpg, .jpeg, or static .webp path located inside the Markdown file's directory and confirm it is within the documented size and dimension limits.

A Mermaid diagram does not render. Use a fenced mermaid code block with valid Mermaid syntax. Expand Mermaid source to inspect it; invalid, oversized, or unusually complex diagrams stay visible as source instead of running unbounded browser work.

Documentation

• OpenAI: Package your plugin

• OpenAI plugin documentation

FlowZone and Markdown Review are independent projects and are not official OpenAI or GitHub products. Product names and marks belong to their respective owners.