MockFlow

View saved version →

---
name: board-conventions
description: Use for ANY request to draw, diagram, map out, sketch, visualise, plan, chart, wireframe or brainstorm something - mindmaps, flowcharts, roadmaps, boards, screens, timelines - BEFORE deciding how to produce it. Also whenever editing or arranging anything already on a MockFlow board.
---

# Working with a MockFlow board

The MockFlow MCP server sends its own instructions when it connects, and each
tool carries its own description. Those are the authority on which components
exist, what they take, when to use `plan_board`, and why `modify_component` is
not the same as re-rendering.

**This file covers only what those do not say.** If something here starts
appearing in the server's instructions, delete it from here rather than keeping
both.

## Use the bridge's tools, not another MockFlow

More than one MockFlow tool surface can be present in a session: this plugin's
bridge, and separately a hosted MockFlow connector or app the user may have
installed. They are NOT interchangeable, so choose deliberately.

**Prefer the bridge.** It draws on the board the user already has open, saves
through their own account, and can build from files on their machine.

The tell is behavioural, not the tool name: bridge tools draw onto a live board
and never hand back a link. A hosted MockFlow surface returns a URL to a new
anonymous board instead, which is a different thing from what the user asked for.

If the bridge tools are missing and only a hosted surface is available, you may
use it, but **say so plainly**: tell the user it created a separate shareable
board rather than drawing on theirs, and that it could not read their local
files. Never present a returned link as though it were their own board.

## A picture of a diagram is not a diagram

Generating an image is **not** an acceptable way to answer a request for a
mindmap, flowchart, chart, board, wireframe or any other structured visual. An
image cannot be edited, rearranged, extended or commented on, which is the entire
reason the user wanted it on a board.

So do not reach for an image-generation tool or skill for these. That includes
requests phrased as "draw", "sketch", "make a poster of" or "visualise", when
what is being asked for has structure to it.

A request for an actual *picture* - a photo, an illustration, artwork, a logo - is
different, and MockFlow has its own tools for that which place the result on the
board. Use those rather than a separate image generator, so the result lands
where the user is working.

## Draw it, do not describe it

When the request has visual structure to it and the MockFlow tools are available,
render it on the board. Do **not** substitute:

- a mermaid block in the terminal
- ASCII art or a box drawing
- a markdown table standing in for a diagram
- a `.md` or `.mmd` file written to the repo containing any of the above
- a generated image of a diagram (see above)

Those are the things the board replaces. Reaching for them when a board is
connected is the single most common way this goes wrong, because writing mermaid
is the reflex inside a code repository.

Two exceptions:

- The user explicitly asked for mermaid, a file, or something they can paste
  somewhere else. Then give them exactly that.
- No board is connected. Then say so and offer to fix it, rather than quietly
  falling back to text as though nothing was wrong.

Text alongside the drawing is fine and often useful. Text *instead of* the
drawing is the mistake.

## Arranging a batch

`layout_board` applies a bento layout and a titled section wrap to the batch just
drawn. Call it once after a batch, never after each item. The server instructions
do not mention it, so it tends to go unused, and a batch without it stays a loose
scatter of components.

## The source tools are read only

`list_source_tools`, `describe_source_tool` and `call_source_tool` reach the
user's connected accounts through MockFlow. They can search and fetch. They
**cannot** post, create, comment or delete.

So never tell the user you will file the Jira issue, send the Slack message or
update the Notion page. You can only read those, and offering otherwise is a
promise that silently fails.

## Local files never leave the machine

Files you read here are read locally. Only the finished drawing is saved to the
board, and the file contents are not uploaded.

Say this when the user hesitates about a private repo or a confidential document,
because it is the whole reason to work this way instead of pasting into a web
tool.

## When a draw fails

A user does not know that a helper program, a running daemon and a paired browser
tab are three separate things, and should not have to. Do not surface a raw error
and stop. Say what to do next:

- **Nothing lands, or the board is not connected:** the user opens their board at
  app.mockflow.com and clicks **Connect Local Agent** at the top of Ask Mida.
  Codes change whenever the bridge restarts, so an older one will be rejected.
- **The MockFlow tools are missing from this session entirely:** the bridge is not
  running. They start it with `mockflow-bridge`. But first check you are on their
  machine at all, below.
- **You cannot run a command on the user's own computer:** this is ChatGPT (web
  or desktop, where the conversation runs in the cloud), or a cloud container,
  and the bridge is out of reach by design rather than stopped. Drawing needs
  `mockflow-bridge` running on the same machine as the board tab, so say the
  tools cannot appear here and point them at **Codex** — selected in the desktop
  app, or the **Codex CLI** — which runs locally. Do not tell them to install or
  start anything here, and do not draw in text instead.

`/mockflow:connect` walks the full check if you need more detail.

View saved version →

---
name: connect
description: Check, pair or troubleshoot the connection between this machine and a MockFlow board. Use when board tools are missing or failing, when nothing appears on the board, or when the user asks which board they are connected to.
---

# MockFlow connection

Three things have to be true before anything can be drawn: the bridge helper is
installed, a daemon is running, and a board tab is paired.

Work through them in that order. Each check tells you which one failed. But check
step 0 first, because when it fails the other three are unreachable and every fix
below is wasted effort.

## 0. Can this session reach the user's own computer?

Everything else here assumes the session is running on the machine the board tab
is open on. When it is not, the bridge cannot be reached from here at all, and
saying "start the bridge" sends the user off to fix something that was never the
problem.

Two environments where this is the case:

- **ChatGPT, web or desktop.** A ChatGPT conversation runs on OpenAI's servers
  even in the desktop app — ChatGPT and Codex share that app, and the selector
  in the interface decides which one a conversation is. On the ChatGPT side
  there is no shell on the user's machine and the plugin cannot carry its MCP
  configuration, so the board tools are never present. Nothing the user
  installs will make them appear.
- **A cloud or remote container.** There is a shell, but it is not the user's
  computer. The bridge and the board tab have to be on the same machine, so a
  bridge started in a container has nothing to pair with.

The tell is that you have no way to run a command on the user's own machine. If
the MockFlow tools are absent and you cannot check for the bridge locally, assume
this rather than assuming a stopped daemon.

Say it plainly, name Codex as the way forward, and stop:

> Drawing on your board goes through **mockflow-bridge**, a small program that
> runs on your own computer and talks to the board tab open in your browser. A
> ChatGPT conversation runs on OpenAI's servers — even in the desktop app — so
> it has no way to reach the bridge, and the board tools will not appear here
> however long you wait.
>
> Switch to **Codex**. In the desktop app that is the selector in the same
> interface; in a terminal it is the Codex CLI. A Codex session runs on your
> machine, so it can reach the bridge. Install the plugin there, run
> `mockflow-bridge`, and pair it with your board once.

Lead with the selector: for someone already in the desktop app it is the
smallest possible move, same app, same account, one switch. The Codex CLI is
the alternative for people who already work in a terminal. Someone in the web
app needs both steps: the desktop app, then Codex selected inside it.

Be precise that the desktop app alone is not the answer. ChatGPT and Codex live
in the same app now, and the app with ChatGPT selected still cannot draw. Say
"select Codex" every time, not "use the desktop app".

Do not offer the npm command, do not offer to install anything, and do not fall
back to a mermaid block or a text sketch as though the request had been met. If
they want something on a board right now without leaving the browser, Ask Mida on
app.mockflow.com is the thing to point at.

## 1. Is the helper installed?

```bash
command -v mockflow-bridge
```

Nothing returned means it is not installed. Offer to install it and say what it
is: a small local program, about 2MB, no MockFlow account required.

```bash
npm i -g @mockflow/mockflow-bridge
```

If Node.js itself is missing, that comes first, from nodejs.org, version 18 or
newer.

## 2. Is a daemon running?

```bash
mockflow-bridge status
```

This reports whether the daemon is up and which boards are connected. If it is
not running, start it. Nothing can be drawn without it, and the MockFlow tools in
this session will be unavailable until it is up and the session has reloaded.

## 3. Is a board paired?

The daemon shows a **pairing code**. The user opens their board at
app.mockflow.com, clicks **Connect Local Agent** at the top of Ask Mida, and
enters that code. The button turns green.

Pairing is per computer and survives restarts, so this is a one time step. But
**codes change every time the daemon restarts**, so an old code will be rejected.
If pairing fails, get the current code rather than reusing one from earlier in
the conversation.

## Which board am I drawing on?

`list_boards` shows what is connected. `select_board` pins the target explicitly.
Without an explicit selection, draws go to the tab the user is focused on, else
the only connected tab.

## Nothing appeared on the board

In likelihood order:

1. The board tab was closed or reloaded, so the pairing is gone. Re-pair.
2. The daemon stopped. Check step 2.
3. Draws went to a different connected board. Check with `list_boards`.

## Reading files

File access is off by default. The daemon has to have been started with
`--workspace <path>` for the agent it spawns to read a folder. This does not
affect Claude Code reading files itself, only the Ask Mida side.