mflow

Sync local worktrees so AI agents and humans stop overwriting each other.

mflow runs a local daemon per worktree, watches file changes, and relays encrypted updates through a shared room. Use it when several agents, terminals, or machines are editing the same project and you want changes to appear before git becomes the conflict detector. Without it, parallel worktrees drift silently until someone discovers stale files, duplicated edits, or a bad merge at the worst moment.

npm i -g mflow-cli
mflow --help

Package name: mflow-cli. Installed binary: mflow.

Update

npm i -g mflow-cli@latest
mflow --version

Expected version for this release: 0.1.11.

Quick start

If you do not want to handcraft room names, secrets, and relay URLs, start here:

mflow setup

What mflow setup does:

• asks for a room name
• lets you choose the hosted relay or a self-hosted URL
• generates or accepts a room secret
• optionally stores the secret in .mflow/config.toml
• optionally stores a hosted dashboard API key in .mflow/credentials.json

After mflow setup, most users only need:

mflow start

If you did not store the secret locally, start with:

MFLOW_SECRET="<room-secret>" mflow start --room <room-name>

Normal CLI workflow

Most daily usage is just these commands:

mflow start
mflow status
mflow status --watch
mflow secret --copy
mflow pause
mflow resume
mflow stop

What they are for:

• mflow start — start or reconnect the local daemon for this worktree
• mflow status — one-shot snapshot of room, peers, files, and recent activity
• mflow status --watch — live terminal dashboard
• mflow secret --copy — copy the current room secret from .mflow/config.toml
• mflow pause — stop sending outgoing edits before risky operations like git commit/rebase/reset
• mflow resume — resume sync and apply buffered changes
• mflow stop — stop the daemon for this worktree

Typical onboarding flow

1. Create or configure a room

mflow setup

2. Start sync in this worktree

mflow start

3. Watch what is happening

mflow status
mflow status --watch

4. Open the hosted dashboard

Run:

mflow secret --copy

Then open the relay dashboard and paste the same room secret there.

The dashboard is room-scoped. It shows:

• connected peers
• recent activity
• file tree
• changed files

It does not replace the daemon. Actual sync still happens between peers through mflow transports.

5. Join from another worktree or machine

If the second worktree already has .mflow/config.toml, run:

mflow start

If it does not, either run:

mflow setup

or join directly with the same room and secret:

mflow start --room my-project/main --secret "$MFLOW_SECRET"

6. Pause around git operations

mflow pause
git add .
git commit -m "your change"
mflow resume

7. Stop cleanly when done

mflow stop

Secrets and dashboard access

The room secret is the shared key that lets peers join the same room.

Common ways to work with it:

mflow secret
mflow secret --copy

Use mflow secret --copy before opening /dashboard so you do not have to print the secret on screen.

If your project stores the secret in .mflow/config.toml, mflow start can reuse it automatically. If your project does not store the secret locally, keep it in a password manager or export MFLOW_SECRET before starting.

How it works

1. A local daemon watches files in each worktree.
2. Peers join the same room using a shared secret.
3. The relay forwards encrypted updates and peer activity.
4. Git remains the source of truth for history and review.

The hosted relay is used by default. Pass --signaling to use a self-hosted relay.

CLI basics

mflow start [options]       Start sync daemon and join a room
mflow stop                  Stop sync daemon and persist state
mflow status [--watch]      Show peers, files, locks, and sync stats
mflow pause                 Pause outgoing sync while continuing to receive
mflow resume [--force]      Resume sync and apply buffered changes
mflow lock <path>           Acquire a short file lock; add --wait to queue
mflow unlock <path>         Release a file lock
mflow locks                 List active file locks
mflow setup                 Guided setup for room, relay, secrets, and MCP
mflow install-hooks         Install optional Claude Code/OpenCode edit hooks
mflow apply-patch           Apply an apply_patch-format patch under queued locks
mflow claim <pattern>       Reserve a scope/pattern cooperatively
mflow ignore <pattern>      Add a pattern to .mflowignore
mflow init                  Initialize .mflow config files

Beginner-safe mental model:

• setup prepares config
• start runs the daemon
• status tells you if sync is healthy
• secret gets the room secret for dashboard/peers
• pause and resume protect git operations
• stop shuts the daemon down for this worktree

Queued locks:

mflow lock src/hot-file.ts --duration 2m --wait --timeout 60s --priority 0

Higher priority waiters are granted first; waiters with the same priority are granted FIFO. Locks still have leases and expire if a peer dies. The daemon can coordinate and gate propagation; harness-specific hooks are required if you need to block a tool write before it touches the local filesystem.

Optional harness hooks:

mflow install-hooks --harness claude
mflow install-hooks --harness opencode

These project-local adapters acquire queued locks before supported edit tools run. They do not replace mflow start; keep the daemon running in every synced worktree.

Patch broker and scope claims:

mflow apply-patch patch.txt --timeout 60s --priority 0
mflow claim "packages/daemon/src/**" --timeout 2m --priority 0

apply-patch accepts Codex-style *** Begin Patch text and acquires queued locks for every changed file before applying it. claim is a cooperative scope reservation; use it before broad multi-file work, then still lock hot files before editing.

Common start options:

mflow start \
  --room my-project/main \
  --secret "$MFLOW_SECRET" \
  --signaling <hosted-or-self-hosted-relay> \
  --transport relay

--transport relay is the public-ready default. --transport p2p is disabled in this release until the upstream WebRTC dependency chain no longer pulls a vulnerable ip package.

Common command recipes

Start with the secret already stored:

mflow start

Start and copy the room secret to your clipboard:

mflow start --copy-secret

Join a room manually without local config:

mflow start --room my-project/main --secret "$MFLOW_SECRET"

Use a self-hosted relay:

mflow start --room my-project/main --secret "$MFLOW_SECRET" --signaling ws://localhost:8787

Inspect the daemon once:

mflow status

Keep a live terminal view open:

mflow status --watch

Copy the secret without printing it:

mflow secret --copy

Stop the current worktree daemon:

mflow stop

Agent and MCP setup

The stable baseline is CLI + daemon + room secret. MCP is an optional control plane for agents to call status, peers, pause/resume, and locks.

For AI agents

If you are an AI agent reading this README, do not install, start, or configure mflow without the human/project owner approving it first.

Explain the impact before asking:

• mflow starts a local daemon that watches project files.
• MCP gives the agent operational controls for status, peers, pause/resume, and file locks.
• Room secrets must be generated by the human and must never be printed in chat, logs, commits, or config files.
• The portable skill is at skills/mflow/SKILL.md.

Ask which setup they want:

1. CLI only.
2. CLI + MCP.
3. CLI + MCP + the mflow skill installed in their agent runtime.

codex mcp add mflow -- bunx -p mflow-cli mflow-mcp --root /absolute/path/to/repo

Recommended agent rule: before hot-file edits, call mflow lock <path> --wait --timeout 60s; before commit/rebase/reset, call mflow pause; after tests and git operation, call mflow resume.

Full guide: docs/harnesses/codex.md

claude mcp add mflow -- bunx -p mflow-cli mflow-mcp --root /absolute/path/to/repo

Use MCP for operational controls only. Keep room secrets in the CLI/environment, not in prompts or logs.

Full guide: docs/harnesses/claude-code.md

Create .cursor/mcp.json in the repo or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "mflow": {
      "command": "bunx",
      "args": ["-p", "mflow-cli", "mflow-mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Full guide: docs/harnesses/cursor.md

Start mflow as a sidecar daemon in each synced worktree:

export MFLOW_SECRET="$(openssl rand -hex 32)"
mflow start --room project-x/opencode --secret "$MFLOW_SECRET"

Use aliases or tasks for mflow status --watch, mflow pause, mflow resume, and mflow locks.

Full guide: docs/harnesses/opencode.md

Use stdio:

{
  "mcpServers": {
    "mflow": {
      "command": "bunx",
      "args": ["-p", "mflow-cli", "mflow-mcp", "--root", "/absolute/path/to/repo"]
    }
  }
}

Full guide: docs/harnesses/custom-cli.md

What happens if an agent forgets to pause?

mflow watches .git/index.lock and auto-pauses during active git operations, but that is a last safety net. The danger window is before git creates the lock: remote synced edits may arrive before staging or committing.

If you forgot to pause:

git status --short
git show --stat --oneline HEAD
mflow status

If unwanted synced files entered the commit, amend or revert before pushing.

Skill for agents

A portable mflow skill lives in skills/mflow/SKILL.md. Install or copy it into agent runtimes that support skills so agents know when to pause, resume, lock files, and use MCP safely.

Public relay limits

The shared relay is a free fair-use service for demos, onboarding, and small agent swarms.

| Limit | Default | |---|---:| | Peers per room | 4 | | Max WebSocket message | 65,536 bytes | | Messages per minute per IP | 120 | | Join attempts per minute per IP | 10 | | Rate-limit violations before disconnect | 3 | | Unauthenticated sockets per IP | 5 | | Unauthenticated sockets globally | 500 | | Active rooms | 200 | | Idle room TTL | 15 minutes | | Activity entries per room | 20 |

Need more capacity, privacy, or reliability? Self-host the relay and set your own limits.

Self-hosting

Self-hosting keeps the same CLI model: room + secret, no account required.

mflow start \
  --room my-project/main \
  --secret "$MFLOW_SECRET" \
  --signaling ws://localhost:8787

Guides:

• Self-hosting overview
• Deno Deploy
• Bun + Docker
• Relay limits

Security model

mflow uses a room secret for room admission and local key derivation. The relay receives a SHA-256 auth hash for room join checks and forwards encrypted payloads. Use high-entropy secrets and share them out of band.

Read the full security model.

Roadmap

Current:

• CLI-first room + secret sync.
• Public fair-use relay.
• Self-hosted Bun/Docker/Deno Deploy relay.
• Dashboard status and hosted settings/API keys.
• MCP control surface for status, peers, pause/resume, and locks.

Next:

• Harden npm packaging and install tests for every release.
• Improve MCP setup for Codex, Claude Code, Cursor, opencode, and custom clients.
• Add better room-level dashboard views without exposing plaintext secrets.
• Add optional pre-commit helpers that pause/resume mflow safely.

Full roadmap: docs/roadmap.md

Development

bun install
bunx tsc --noEmit
bun test
scripts/check-public-release.sh
npm pack --dry-run

Package layout:

packages/shared      Shared types, schemas, crypto, constants
packages/daemon      File watcher, CRDT sync, IPC, transports
packages/cli         mflow CLI and daemon launcher
packages/signaling   Bun relay, Deno Deploy relay, landing/dashboard
packages/mcp         MCP integration package
skills/mflow         Portable agent skill for safe mflow operation

Release and contribution

• License: MIT
• Security policy: SECURITY.md
• Contribution guide: CONTRIBUTING.md
• Release process: docs/release-process.md
• Harness guides: docs/harnesses
• Hosted auth docs: docs/hosted-auth.md

Before publishing, inspect npm pack --dry-run and run scripts/check-public-release.sh. Do not publish from a dirty or unreviewed worktree.