reflow2

Set up reflow2.

Pick how you will run it. Each way is complete on its own. New here? See what reflow2 is first.

On your own computer VS Code, where MCP is blocked A server for a team

Releases, with every version's notes, are on GitHub. Several designs in one effort? Once reflow2 is set up, make a hub.

On your own computer

For a coding agent that speaks MCP: Claude Code, OpenCode or Grok Build. reflow2 runs on your machine and keeps each design in the project's own folder. Linux (x86_64 or arm64) or macOS.

1 Install it, once per computer

curl -fsSL https://raw.githubusercontent.com/flo2-connector/reflow2/main/tools/install.sh | sh

That puts reflow2-mcp and the reflow2 command in ~/.local/bin and registers reflow2 with Claude Code and OpenCode for every project on the computer. A folder you never design in stays untouched.

If the GitHub CLI (gh) is installed, the installer downloads through it, so be signed in first (gh auth status). Without gh it uses plain curl.

2 Start a design

cd my-project
claude            # or: opencode

Grok Build is set up per project: run reflow2 init . --harness grok in the project first, then start grok there.

Then say one of these to your agent:

3 A repository you share (optional)

If other people or other computers work on the project, add the in-repo part, so their agent is told reflow2 keeps this project's design:

reflow2 init .

Commit what it writes and your design's export. The .reflow2/ folder stays local.

4 Updating

  1. Export each design and commit it, and copy each project's .reflow2/ folder somewhere safe. An older reflow2 refuses an export written by a newer one, so that copy is your way back.
  2. Run the install command again. It keeps the binary it replaces as ~/.local/bin/reflow2-mcp.<old version>.
  3. In each repository where you ran reflow2 init ., run reflow2 update, so the slash commands it wrote there match the new release. Files somebody edited are kept.
  4. To roll back, copy that file over ~/.local/bin/reflow2-mcp and put your copy of .reflow2/ back.

VS Code, where MCP is blocked

For an organisation whose Copilot policy blocks third-party MCP servers. The agent reaches reflow2 through the terminal instead: reflow2 read … for anything that only reads, reflow2 write … for anything that changes the design. Linux or macOS.

1 Install it

The same command as on your own computer:

curl -fsSL https://raw.githubusercontent.com/flo2-connector/reflow2/main/tools/install.sh | sh

Check it:

reflow2 --version
reflow2 read --list | head -3

2 Set up each repository

In each repository you design in, preview first, then write:

reflow2 init . --harness vscode-cli --check    # shows what it would write; writes nothing
reflow2 init . --harness vscode-cli
git status --short

It writes no MCP configuration. Under .github/ it writes an instructions file, VS Code hooks, one skill per reflow2 skill and the slash commands. Beside them it writes .reflow2.toml, which names where the design's export is kept: the export the design already has, or docs/design/<repository>.json. Every write, the Stop hook and the CI check read that one line, so they keep the same file current. Commit them, so everyone on the project gets the same setup:

git add .github .reflow2.toml && git commit -m "reflow2: VS Code terminal route"

3 Let reads run without asking

Add this to your own VS Code settings. Every read runs without a prompt, and each write still asks:

"chat.tools.terminal.autoApprove": {
  "/^reflow2 read /": true
}

4 Start a chat

Open the repository in VS Code and start a chat. A hook checks the design (loop_status) when the session starts and names the first read for where the design stands (graph_report as Markdown), and another says what is owed when it stops. If nothing appears:

What this route reaches. reflow2 read and reflow2 write work on a design on your own machine. A long reply fits the budget_chars you pass, and compare_designs between two exports reads one list a page at a time with list and offset. A reply prints as one line of JSON; pipe it to jq to read it laid out. A hub on your own machine searches and checks every member it pins by a committed export (tracked_designs: true, see hubs). This route cannot reach a design hosted on flo2.io, so a hub's live view over its members, its merged search and reads across designs by graph id need an MCP client connected there. Each release's notes say what it adds to this route.

Upgrading a computer that already has reflow2

Close VS Code first, so nothing has a design open. Then look before you change anything:

command -v reflow2 reflow2-mcp
reflow2-mcp --version
head -2 "$(command -v reflow2)"    # "installed by reflow2_install.py" means the installer's wrapper
command -v gh && gh auth status

If reflow2 is a symlink to the binary rather than the installer's wrapper, that is fine: the installer replaces the link and leaves the binary alone.

Back up before anything is replaced. Run this once, then the second part in each repository you design in:

B=~/reflow2-backup-$(date +%F); mkdir -p "$B"
cp -p ~/.local/bin/reflow2-mcp "$B/"

# in each repository:
mkdir -p "$B/$(basename "$PWD")" && cp -a .reflow2 "$B/$(basename "$PWD")/"
git status --short    # commit the design's export first; git keeps that copy

Then install, check and set up each repository as in steps 1 to 3. Lines the installer prints about Claude Code or OpenCode are harmless on a computer without them. To install one version rather than the newest, put REFLOW2_VERSION=vX.Y.Z before sh.

If you wrote your own instructions file for this route before reflow2 set it up, for example under ~/.config/Code/User/prompts/ (on macOS, ~/Library/Application Support/Code/User/prompts/), move it into your backup folder after every repository you use has been set up. Until then, it is what tells the agent about reflow2 in the repositories still waiting.

To roll back: copy the old binary back over ~/.local/bin/reflow2-mcp and put each repository's .reflow2/ back from $B. An older reflow2 refuses an export a newer one wrote.

The full guide, with what each command does and what still has limits: using reflow2 in VS Code without MCP.

A server for a team

One reflow2 that several people's agents reach over HTTP, from the published container image, on Docker or Kubernetes.

1 The image

ghcr.io/flo2-connector/reflow2/reflow2-mcp:<version>

2 Run it

docker run -d --name reflow2 \
  -p 127.0.0.1:8080:8080 -v reflow2-data:/data \
  --log-opt max-size=10m --log-opt max-file=3 \
  ghcr.io/flo2-connector/reflow2/reflow2-mcp:<version>

3 Decide who may call it

Give it your sign-in provider, and it checks every caller's bearer token itself:

docker run … ghcr.io/flo2-connector/reflow2/reflow2-mcp:<version> \
  --http-oidc-issuer https://sso.example.org/realms/team \
  --http-public-url https://reflow2.example.org \
  --http-contributor-id 'who:{preferred_username}'
Upgrading a running server
  1. See what you run now:

    kubectl -n <namespace> get deploy <name> -o jsonpath='{.spec.template.spec.containers[*].image}'
    kubectl -n <namespace> exec deploy/<name> -- /usr/local/bin/reflow2-mcp --version
    # on Docker:
    docker exec reflow2 /usr/local/bin/reflow2-mcp --version
  2. Snapshot the volume behind /data. That snapshot is your rollback. An older reflow2 refuses an export a newer one wrote, so an old export will not take you back. For a portable copy as well, call export_graph with a path under /data from any MCP client before you roll out.
  3. Upgrade everything that opens the team's designs at the same time: the server, and anyone whose own reflow2 imports its exports.
  4. Read "What a consumer or operator should know" in the CHANGELOG for every version you skip. One that surprises agents: from 0.78.0, an argument a tool does not take is refused instead of ignored, and the refusal names the tool and the field. Drop what it names.
  5. Change the image (and its name, if it is still the old one) and roll out.
  6. Afterwards, loop_status may open with "THIS DESIGN HAS NEVER BEEN EXPORTED" or say the design is ahead of its export. Export as it says, and commit the file.

To roll back: pin the old image again (the old name, for 0.78.0 and earlier) and restore the snapshot.