Installation

Clone flowx into a shared workspace location

Clone the repo into your workspace using a Git folder, under /Workspace/Shared (e.g. /Workspace/Shared/flowx).

Copy the skills into your skills folder

Genie Code picks up skills from your .assistant/skills folder automatically. Copy skills/ into a user-level folder:

databricks workspace import-dir skills /Users/<your-email>/.assistant/skills

Or make flowx available to all workspace users with a workspace-level folder:

databricks workspace import-dir skills /Workspace/.assistant/skills

Skills fire automatically when their description matches your request. To invoke one explicitly, use the @ prefix (e.g. @flowx-migrate translate the ADF pipelines I exported to /Volumes/main/default/adf_export). See the Genie Code Skills docs for more.

Run the setup skill

Ask your agent to "set up the flowx environment" (or run @flowx-setup). On Databricks, setup detects the environment and prepares the MCP path — it does not create a virtual environment, because the phases run through the deployed app rather than a local interpreter.

Deploy the MCP server

Deploy the mcp-flowx Databricks App from the flowx checkout. The recommended way runs entirely in the workspace, including on serverless compute:

Open and run the app/deploy_app.py notebook. Set its repo_root widget to your checkout (e.g. /Workspace/Shared/flowx); it uses the Databricks SDK to stage a self-contained source bundle (app entrypoint plus a vendored copy of the flowx package) to /Workspace/Shared/mcp-flowx and create/deploy the app. The notebook prints the app URL; the MCP endpoint is <app-url>/mcp.

Grant access

• App access: grant Can use on the mcp-flowx app to the users or service principals that will call it (Apps UI → Permissions, or databricks apps set-permissions).
• Data access: grant the app's own service principal access to the catalogs, schemas, and Unity Catalog volumes the migration reads from and writes to, plus any SQL warehouse used by the reporting commands (flowx(command="record_results") / flowx(command="install_dashboard")).

Register the MCP server in Genie Code

MCP servers are available in Genie Code Agent mode:

1. In the Genie Code panel, click ⚙ Settings.
2. Under MCP Servers, click + Add Server.
3. Choose Custom MCP server and select the mcp-flowx Databricks App.
4. Click Save.

The single flowx tool is available when you use Genie Code in Agent mode.

Verify

Open the health endpoint <app-url>/ (returns {"status":"ok"}), or ask Genie Code "what flowx MCP tools are available?". You should see the single flowx tool. You can now run @flowx-migrate (or the individual phase skills).

Install the plugin

flowx is distributed through its Claude Code marketplace. From a Claude Code session:

/plugin marketplace add databricks-solutions/flowx
/plugin install flowx@flowx

Then run /reload-plugins to activate it.

cp -R skills/{flowx-setup,flowx-discover,flowx-convert,flowx-package,flowx-migrate} ~/.claude/skills/

Run the setup skill

Run /flowx:flowx-setup (or ask "set up the flowx environment") once before any phase. flowx's Python modules depend on third-party packages (pyyaml, databricks-sdk, sqlglot), so setup provisions an isolated virtual environment via scripts/bootstrap.sh. It will:

1. Check that python3, pip, and the venv module are available.
2. Create the virtual environment at <plugin_dir>/.venv.
3. Install requirements.txt into it with pip.
4. Write the resolved interpreter path to the marker file <plugin_dir>/.migration-venv, which the phase skills read.

The environment is created once and reused. No uv is required for plugin users.

(Optional) Run the phases over a local MCP server

The phase skills call the venv CLI directly, so this step is optional. To instead drive the phases through MCP tools locally, install the MCP server stack into the venv and register the stdio server with your MCP client:

PY="$(cat <plugin_dir>/.migration-venv)"
"$PY" -m pip install "mcp>=1.12" "uvicorn>=0.30" "starlette>=0.40"
PYTHONPATH="<plugin_dir>/src" "$PY" -m flowx.mcp

{
  "mcpServers": {
    "flowx": {
      "command": "<plugin_dir>/.venv/bin/python",
      "args": ["-m", "flowx.mcp"],
      "env": { "PYTHONPATH": "<plugin_dir>/src" }
    }
  }
}

Verify

Open Claude Code and ask "What flowx skills do you have available?". You should see all five skills (flowx-setup, flowx-discover, flowx-convert, flowx-package, flowx-migrate). Invoke them with /flowx:flowx-migrate, /flowx:flowx-discover, etc.

If you hit a ModuleNotFoundError while running a phase, the venv is missing or incomplete — re-run /flowx:flowx-setup. Every Python command the skills run uses the interpreter recorded in <plugin_dir>/.migration-venv, with src/ on PYTHONPATH:

export PYTHONPATH="<plugin_dir>/src"
PY="$(cat <plugin_dir>/.migration-venv)"
"$PY" -m flowx.adapter inputs discover