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:
/genesis I want to build …for something new. A paragraph is plenty./adoptfor code, hardware or documents that already exist./wherefor a design somebody else started and handed you.
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
- 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. - Run the install command again. It keeps the binary it replaces as
~/.local/bin/reflow2-mcp.<old version>. - In each repository where you ran
reflow2 init ., runreflow2 update, so the slash commands it wrote there match the new release. Files somebody edited are kept. - To roll back, copy that file over
~/.local/bin/reflow2-mcpand 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"
- If some teammates can use MCP, use
--harness vscode-cli,vscode. reflow2 updaterefreshes these files later. Files somebody edited are kept, and files you wrote yourself are left alone.reflow2 init --removetakes reflow2's files back out of a repository and leaves its design and export alone;--remove --checkshows what it would do first. After it,reflow2 updaterefuses there untilreflow2 initinstalls again.- If
git statusshows changes outside.github/and.reflow2.toml, read them before adding them. - In a repository you do not own, such as one a hub of yours designs, commit nothing there. Write
only
.reflow2.toml, with[export]andpath = "…"naming where you keep its export (a path into your hub's repository works), and list that file in.git/info/exclude.
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:
- Your organisation may have turned agent hooks off (
chat.useHooks). - VS Code's own terminal must find
reflow2. Runcommand -v reflow2there. If it finds nothing,~/.local/binis missing from that terminal'sPATH.
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>
- One image for linux/amd64 and linux/arm64. It is public, so pulling needs no token.
- Pin it by the digest in that release's notes (latest release). A tag can be pushed again; a digest names one image forever.
- The image moved in 0.79.0. Images up to 0.78.0 are only at
ghcr.io/sligara7/reflow2/reflow2-mcp, and that name gets no newer release, so a manifest still pinning it never moves. Change the name when you upgrade.
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>
- This listens on this machine only. Until step 3 is done, anything that reaches the port can write the design, so open it to others only after that.
- Designs live under
/data. Keep it on a volume, and back that volume up. - By default it serves one design, at the server's root address. Set
REFLOW2_REGISTRY_ROOTto serve every design under a folder instead, each at/g/<design id>/. It then raises its open-file limit as far as the system allows when it starts, and warns if its open designs could still run out of file handles. - Readiness is
GET /readyz(200 only while the design is served) and liveness isGET /healthz. The readiness answer also says how many files the server has open against its open-file limit. - Run one replica per store: a design has one writer. On a rolling update the new pod takes the store over when the old one lets go, and turns ready without a restart.
- Cap the log as above. Docker's default log has no size limit.
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}'
- The same settings work as environment variables:
REFLOW2_OIDC_ISSUER,REFLOW2_PUBLIC_URL,REFLOW2_CONTRIBUTOR_ID. - Without a sign-in provider or a trusted gateway in front, a server set up for others serves reads and proposals only. A server set up as neither is a local server: anything that reaches its port can write the design, so keep that port private.
- reflow2 does not handle TLS. Put a TLS proxy in front, and give its
https://address as--http-public-url.
Upgrading a running server
-
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 - 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, callexport_graphwith apathunder/datafrom any MCP client before you roll out. - Upgrade everything that opens the team's designs at the same time: the server, and anyone whose own reflow2 imports its exports.
- 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.
- Change the image (and its name, if it is still the old one) and roll out.
- Afterwards,
loop_statusmay 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.