Quickstart

Install the extension and read the selected device from Bitwig. This first check is read-only: it does not change your project, start playback, or require MCP. Already installed? Skip to Verify the connection.

1. Check prerequisites

• Bitwig Studio 6.1.1 for private Grid and native arranger support. 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.

Download the matching bitwig-grid-bridge-VERSION.zip from GitHub Releases, extract it, and open a terminal in its top-level folder. If the required release is not available, follow Build from source first.

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

2. Install the extension

On Linux, run from the extracted bundle folder:

mkdir -p "$HOME/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension "$HOME/Bitwig Studio/Extensions/"

For other installation paths, see Installation. If you built and installed from source, skip the copy command and keep your terminal in the checkout root.

Restart Bitwig. Open Settings → Controllers, add Bitwig Grid Bridge, and enable it. Then open a project and select a device; a copy of a project from examples/projects/ is a useful place to learn.

Reload is asynchronous. The read-only check below establishes readiness; never use a mutation to test whether the extension loaded.

3. Verify the connection

From the bundle folder or checkout root, run:

python examples/automation/grid_bridge_demo.py inspect

Use python3 instead if that is your Python 3 command. The script prints three JSON responses: bridge capabilities, selected-device inspection, and exposed controls. Each successful response contains "ok": true. Confirm the reported extension/host/API match your installation and the device matches your selection in Bitwig. If the script fails, use If something fails.

Once these match, the direct bridge connection is working. You can stop here without changing the project.

If you selected a Grid, this optional read-only check shows its graph capability and, when available, its modules and connections:

python examples/automation/grid_bridge_demo.py graph

graph_available: false does not mean the bridge connection failed. Exposed controls may still be available, but do not attempt graph edits for that selection.

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.

For a guided musical exercise, follow the Minimal techno quickstart. It authors clips in Bitwig's UI and identifies where optional bridge or agent tools can help.

5. MCP-based interaction

To use natural-language briefs or MCP workflows, follow Install the optional MCP adapter, then connect your client using the Agent integration reference. Only after that setup should you run the MCP tool 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.

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 command.
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.
Wrong version or device	Confirm the installed release and selected device before continuing.
Graph unavailable	Select a supported Grid, or use exposed-control commands instead.

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