Cheat sheet

Copy the smallest block that matches the task. Read state before every live change.

Install and verify

make install-extension
python examples/automation/grid_bridge_demo.py inspect
python examples/automation/grid_bridge_demo.py graph

For a release asset, copy BitwigGridBridge.bwextension directly instead of running Maven.

Start the optional MCP adapter

uv sync --frozen
BITWIG_MCP_GRID_BRIDGE_ENABLED=true uv run bitwig-mcp

The MCP configuration, exact tool contracts, and safe sequences are in the agent reference and agent workflow playbook.

The adapter can start without Bitwig for offline song/export and local Nitro work. Live private bindings are exact Bitwig 6.1.1; Controller API minimum, compile and current-host API are 25.

Compose and deliver

Step	Tool and review boundary
Draft without a session	grid_track_plan with supported musical constraints
Own/revise a review	grid_track_start, grid_track_revise, grid_track_status
Export source MIDI + manifest	grid_track_export with exact 64-hex song revision
Observe target	grid_song_state: exact token, selection, recording, capacity
Import once	grid_track_import: session, revision, source hash, token, confirmation
Observe clips	grid_track_import_status, then grid_inspect_arranger(track_index) per role; check completeness, bounds, source counts/spans and loops
Make linear clips non-looping	grid_set_clip_loop: track_index, observed native_clip_id, expected_loop_enabled, enabled: false, fresh expected_project_token, authorization; re-inspect
Set global tempo/meter	grid_song_transport, explicit tempo/meter, fresh token
Play/stop safely	grid_song_transport, explicit play/stop, fresh token
Seek safely	grid_song_transport, operation: "seek", position_beats 0–24576 quarter-note beats, fresh token and authorization; read back before separate play
Disable global arranger repeat	grid_song_transport, operation: "loop", boolean enabled: false, fresh token and authorization; read back arranger_loop_*; not a clip-loop edit
Mute/arm a track	grid_set_track_state, current bank index and token
Checkpoint native project	grid_song_save, fresh expected_project_token, authorization, optional output_dir parent; require no recording/pending save and capabilities.project_save: true

Native import uses a derived MIDI without tempo/meter events; the full source export is unchanged and both hashes are reported. This is not a generic raw-MIDI sanitizer. Inspect clips and disable loops for linear scores: source summaries are not loop-expanded playback. Replace unintended import-created Organ devices, verify role chains, then listen. Never replay an ambiguous import or mutation. See full workflow.

Native save is not MIDI export or Collect and Save. A fresh private bitwig-project-* child must be outside existing Bitwig project folders; the replacement-capable host writer is not a general atomic no-clobber API. Retain output_directory on requires_observation; inspect it and project_save_pending, never replay. Completion/file presence proves neither full saved-content equivalence nor audio; external assets may remain external.

Read-only Nitro

grid_nitro_status → search_grid_nitro → inspect_grid_nitro only with the pinned extra and already authorized local keys. Catalog discovery needs no keys. The archive had 517 members/513 .nitrobin modules; live status was available_unloaded with matching upstream 0.2.0 and missing_keys, not DSP decryption. Static evidence is not native parameter metadata or audio verification.

Read and preview

get_grid_capabilities
get_selected_device_state
grid_shape_start(brief="...")
grid_shape_compose(session_id="...", controls={...})
grid_shape_status(session_id="...")

Apply and recover

grid_shape_apply(session_id="...", revision=N, confirm=true)
grid_shape_status(session_id="...")
grid_shape_undo(session_id="...")
grid_project_undo
grid_project_redo

Graph operations

All graph mutations require confirm: true or explicitly authorized cooperative: true.

Operation	Tool
Inspect capabilities	get_grid_capabilities
Read the graph	get_grid_graph
Analyze topology hypotheses	grid_analyze
Resolve musical units	grid_resolve_parameter_value → native value and revision
Review additive recipe	grid_patch_start, grid_patch_status
Apply one verified step	grid_patch_step with exact integer session revision
Find modules	search_grid_modules
Find modulators	search_grid_modulators
Insert a module	grid_insert_module
Set a module parameter	grid_set_module_parameter
Connect modules	grid_connect_modules
Disconnect an input	grid_disconnect_module
Clear selected graph	grid_clear_graph: required expected_revision and authorization; retain before snapshot and read back
Undo/redo host work	grid_project_undo, grid_project_redo

Pass the reviewed graph's expected_revision for guarded direct mutations. Native parameter IDs and option backing values come from live metadata; do not guess units or option indexes. Frozen sessions stop, not retry.

Selected device

Need	Tool
Navigate device	grid_navigate_device: first, next, previous, parent
Inspect sibling devices	grid_list_devices: 16-sibling window, identities/token; check window_complete
Discover/insert/replace device	search_bitwig_devices, grid_insert_device: device_id, position (before/after/start/end/replace), required expected_selection_token, authorization
Remove selected device	grid_remove_device: required expected_selection_token, authorization
List tracks, including hidden group children/FX/master	grid_list_tracks
Select a track	grid_select_track
Set exposed parameters	set_selected_device_parameters
Save a snapshot	save_parameter_snapshot
Compare snapshots	compare_parameter_snapshots
Restore a snapshot	apply_parameter_snapshot

Refresh the selection token after navigation/writes. Start/end support empty tracks; before/after/replace need a selected device. Null tokens preserve public reads but cannot authorize native edits. MIDI import can supply Organs: replace unintended instruments rather than stacking them.

Select by the returned bank index, not native position or a main-track-only ordinal. MCP exposed-control values use 0–128; shaping uses 0–1; native Grid parameters use their own observed domains.

Live-set agency

Need	Tool
List live-set styles	grid_list_live_set_styles
Plan roles, scenes, and macros	grid_live_set_plan
Discover current host gestures	grid_list_actions
Invoke an exact host action	grid_invoke_action (confirmation required)

Every macro needs a bounded range, neutral value, and reset gesture. Host action IDs are dynamic; list them in the current Bitwig session and never guess them.

Example commands

python examples/automation/grid_bridge_demo.py inspect
python examples/automation/grid_bridge_demo.py graph
python examples/automation/grid_bridge_demo.py sweep \
  --index 2 --minimum 0.2 --maximum 0.8 --duration 4
python examples/automation/grid_bridge_demo.py insert-fx-grid --position after

sweep restores the original value by default. insert-fx-grid undoes the insertion by default. Add --keep only when you intend to retain a change.

Common messages

Message	Action
Bridge unavailable at 127.0.0.1:8765	Enable the extension for live work; offline workflows remain available.
Extension just copied	Wait for asynchronous reload and read-only capability/readiness; refresh identities before writes.
graph_available: false	No graph work; exposed controls/offline workflows may still work.
confirm must be true	Review the mutation and pass explicit confirmation.
stale draft revision	Read status and compose a new revision.
Selected device changed	Re-read state; do not write from a stale snapshot.
Null/stale selection token	Public reads may work; native edits require a fresh non-null token for the intended selection.
Frozen patch or stale graph revision	Stop and observe; no automatic replay/rollback.
Queued/submitted import	Inspect receipt and actual arranger; not proof of notes/audio.
Import timeout or consumed attempt	Observe; do not duplicate the import.
Nitro missing/invalid prerequisites	Read remediation; never extract keys or infer decryption.
Unexpected result	Use the matching undo or restore a named snapshot.