Documentation menu
On this page

Get from an installed extension to a read-only live-device check without setting up MCP. This first check does not change your project or start playback. Already installed? Skip to Verify the connection.

1. Check prerequisites

You need:

  • Bitwig Studio 6.1.1 for the version-gated native Grid surface. The public bridge requires Controller API 25; see compatibility.
  • Python 3.10 or newer for the verification script. It uses the standard library; no uv, Python packages, or MCP client are needed for this check.
  • The full release bundle, which supplies both the extension and the examples/automation/grid_bridge_demo.py script.
  • A local account that can write to the Bitwig Studio Extensions directory.

Keep a project copy for experiments. Download the matching bitwig-grid-bridge-VERSION.zip from GitHub Releases, replace VERSION with the release number you downloaded, extract it, and open a terminal in its top-level folder. If the required release is not available, use the advanced source-build alternative below.

The standalone .bwextension does not include the script. If you installed that asset, get the matching full bundle or a source checkout before continuing.

2. Install the extension

The commands below assume that your terminal is already in the extracted bundle folder and that BitwigGridBridge.bwextension is at its top level. Open the disclosure for your platform; no JavaScript tabs or MCP setup are required.

macOS
mkdir -p "$HOME/Documents/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension \
  "$HOME/Documents/Bitwig Studio/Extensions/BitwigGridBridge.bwextension"
Linux
mkdir -p "$HOME/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension "$HOME/Bitwig Studio/Extensions/"
Windows PowerShell

Run from the extracted bundle folder:

$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\BitwigGridBridge.bwextension (Join-Path $extensions 'BitwigGridBridge.bwextension')
Advanced: build from source

A release bundle is the shortest path. For a source checkout, the direct read-only check still needs only Python; the build itself needs Java 21 or newer and Maven.

On macOS or Linux, make install-extension is the supported build-and-install path from the checkout root. The Makefile selects ~/Documents/Bitwig Studio/Extensions on macOS and ~/Bitwig Studio/Extensions on Linux:

git clone https://github.com/critx-jt/bitwig-grid-bridge.git
cd bitwig-grid-bridge
make install-extension

For a nonstandard macOS or Linux destination, pass an absolute path:

make install-extension BITWIG_EXTENSIONS_DIR="/absolute/path/to/Extensions"

On Windows PowerShell, use Maven and copy the resulting extension explicitly; the Unix make install-extension path does not select a Windows directory:

git clone https://github.com/critx-jt/bitwig-grid-bridge.git
Set-Location bitwig-grid-bridge
mvn -B -f extension/pom.xml package
$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\extension\target\BitwigGridBridge.jar (Join-Path $extensions 'BitwigGridBridge.bwextension')

Keep the terminal in the checkout root for the verification command below. uv is only needed later if you choose the optional MCP server.

After the copy or source build:

  1. Save your work in Bitwig, then fully restart Bitwig. A public ControllerHost.restart can retain an already loaded class definition and is not proof that a replacement was loaded.
  2. Open Settings → Controllers, add Bitwig Grid Bridge if it is not listed, and enable it. Keep only one enabled bridge controller instance.
  3. Open a project and select the device you want to inspect. A project from examples/projects/ is a useful starting point, but device names vary.

Do not use a mutation or a throwaway native attach probe to test whether the extension loaded. The read-only check is the readiness test.

3. Verify the connection

Run the included client from the bundle folder or checkout root, not from the Extensions directory. It connects to the local endpoint 127.0.0.1:8765 and makes three read-only requests.

On macOS or Linux:

python3 examples/automation/grid_bridge_demo.py inspect

If python3 is not your Python 3 command, use python instead. In Windows PowerShell, use the Python launcher or the installed python command:

py -3 examples\automation\grid_bridge_demo.py inspect

What success looks like

The script prints three JSON responses in this order: capabilities, selected device inspect, and selected-device state. Confirm these schema fields; the values below are a representative field checklist, not captured output:

Response Required fields to inspect
capabilities ok: true, protocol: 4, host_version, host_platform, and graph_available
inspect ok: true, exists: true, name, and device_type
state ok: true, exists: true, name, device_type, selection, and parameters

Each parameters entry exposes the fields index, exists, name, value, and display. The selected name and device_type must describe the device currently selected in Bitwig; do not compare them with a fixed fixture name. The supported host is Bitwig 6.1.1, while host_version and host_platform report what the running extension sees.

The connection is successful when all three responses contain ok: true, the capabilities response reports protocol: 4, and the inspect/state identity fields match the selected Bitwig device. Stop here if you only need the direct bridge; no MCP setup or project mutation is necessary.

If any response is missing, has ok: false, reports a protocol other than 4, or reports exists: false for the device you selected, stop and use If something fails before doing anything else. A graph_available: false response is not a failed bridge connection, but it is a hard stop for graph inspection or graph edits: select a supported Grid or use only the public controls whose capability flags are true.

If the selected device is a supported Grid, this optional read-only command shows its graph capability and, when available, modules and connections:

On macOS or Linux:

python3 examples/automation/grid_bridge_demo.py graph

In Windows PowerShell:

py -3 examples\automation\grid_bridge_demo.py graph

graph_available: false does not mean the bridge connection failed. Do not invent graph modules, ports, cables, or revisions when the graph is unavailable.

Optional next musical step: in a project copy, follow the Minimal techno quickstart to build a short loop; it identifies which steps stay in Bitwig and where optional bridge or agent tools can help.

4. Script-based interaction

Use Automation scripts for direct commands, including bounded parameter sweeps. Read each command's effect and recovery behavior before running it on a copy of your project. Treat every later mutation as observe → preview → apply → verify, and read state after an ambiguous result before retrying.

5. MCP-based interaction

MCP is optional. If you want natural-language briefs or MCP workflows, first read the MCP startup and client configuration guide, then follow Install the optional MCP server. The direct inspect check above should already succeed before you attempt live MCP calls.

After the client starts, call tools/list and begin with the read-only calls get_grid_capabilities, get_selected_device_state, and grid_song_state. Stop before any mutation if the intended checkout, tools/list, native capabilities, or selected state do not match. Only then use the MCP sequences in Producer workflows.

The adapter can also compose and export MIDI offline. Starting it without Bitwig does not establish a live connection; inspect again before live work. Offline export is an artifact and does not import a project, realize voices, render audio, or save Bitwig.

If something fails

What you see Next step
Script file not found Open a terminal in the extracted full bundle or checkout root, not the Extensions directory.
Python command not found Install Python 3.10+ or use your system's python3, python, or Windows py -3 command.
Extension cannot be enabled Confirm the .bwextension is in the platform directory above, keep one bridge controller instance, save work, fully restart Bitwig, and enable it again.
Bridge unavailable / connection refused Confirm Bitwig is running and the extension is enabled. Check that no second instance owns 127.0.0.1:8765, then retry the read-only inspect check.
ok is false or protocol is not 4 Stop. Confirm the running extension and host match the supported installation; do not test with a mutation.
exists is false or the name/type is wrong Select the intended device in Bitwig, then rerun the read-only inspect command. Device names vary.
Wrong version or device Confirm the installed release, supported Bitwig version, and selected device before continuing.
Graph unavailable Select a supported Grid, or use exposed-control commands instead. Do not invent graph identities or revisions.

For loading errors and adapter problems, see Activation and troubleshooting. If a later mutation times out, stop and observe state; do not repeat it.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.