Openbridge Debug

OpenBridge Debug via Mini-Machine

This skill replaces the old local OpenBridge automation MCP flow.

Use a remote macOS machine plus full computer-use instead:

• machine.sh creates/lists/gets/stops mini-machine sessions and requires a request description for each new machine.
• publish_branch_for_machine.sh snapshots local changes to a git branch so the remote Mac can build them directly; a local compile pass is optional, not required.
• rerun_setup_on_machine.sh reruns setup on an already-running machine so OpenBridge reopens with the updated branch after you push.
• setup_bridge_on_machine.sh clones OpenBridge on the remote Mac, builds OpenBridge, and opens the app.
• vnc is the actual computer-use tool for screenshots, clicks, typing, keys, and scroll.

Prerequisites

From the local machine:

gh auth status
python3 -m pip install --user --break-system-packages vnc-computer-use   # if `vnc` is missing

If your Python install is externally managed and you do not want --break-system-packages, install vnc-computer-use with a virtualenv or pipx instead.

You need repo + workflow scopes for gh.

For private repo clone inside the remote macOS machine, use one of these:

1. gh auth login on the machine.
2. Export CUEBOARD_GH_TOKEN on the machine before cloning.
3. Export CUEBOARD_REPO_URL to a clone URL the machine can access.

Default workflow

You do not need a successful local build before creating or using a machine. A remote machine build can be your first compile/validation pass; a local build is only an optional preflight when you want faster feedback before pushing.

1. If local changes are not pushed yet, publish them to a branch (local compile optional)

If you want a quick local preflight before pushing, run from the repo root:

cd web && yarn install --immutable && yarn build:embedded
cd ../macos && BUILD_CONFIGURATION=UnsignedDebug bash DevKit/Scripts/workspace_build_debug.sh

If you do not need the local preflight, skip straight to the publish step. In either case, push the branch snapshot so the remote Mac can do the compile/validation pass:

macos/DevKit/skill/publish_branch_for_machine.sh \
  --message "wip: describe the current OpenBridge fix" \
  --branch your-branch-name

That prints the matching machine-side setup command.

1b. When a machine is already running and you want the updated OpenBridge there quickly

After you push the latest branch snapshot, run:

macos/DevKit/skill/publish_branch_for_machine.sh \
  --branch your-branch-name \
  --message "wip: describe the latest OpenBridge change"

macos/DevKit/skill/rerun_setup_on_machine.sh \
  --run-id <run-id> \
  --branch your-branch-name

If the branch is already committed and clean locally, omit --message from the publish step.

This keeps the update flow atomic:

1. stages/commits local changes when needed
2. pushes the branch to origin
3. reruns setup on the still-running machine from a second explicit command
4. updates the existing checkout, rebuilds OpenBridge, kills the older OpenBridge process, and reopens the new one

Forward any extra machine setup flags after --, for example:

macos/DevKit/skill/rerun_setup_on_machine.sh \
  --run-id <run-id> \
  --branch your-branch-name \
  -- --skip-open

2. Create a macOS machine

Always create a fresh mini-machine for your own validation run. Do not take over or reuse a machine that someone else may already be using, even if it looks idle. If you need to continue your own in-flight debugging session, only reconnect to the machine that you created for that same task.

macos/DevKit/skill/machine.sh new "Validate OpenBridge on branch your-branch-name"

Save:

• run id
• VNC URL
• VNC user
• VNC password
• SSH command

Use macos/DevKit/skill/machine.sh list to see active run titles/request descriptions, and get <run-id> if you need the connection info later.

3. Connect with full computer use

vnc connect tunnel.eyhn.in::<vnc-port> --username <user> --password=<password>

Always drive the UI with the full screenshot loop:

vnc get_screenshot -o /tmp/bridge-machine.png
# inspect the screenshot
vnc left_click <x> <y>
vnc type "text"
vnc key enter
vnc scroll down:400 700 500
vnc get_screenshot -o /tmp/bridge-machine-after.png

Rules:

• Take a screenshot before clicking.
• Click the center of the target, not the edge.
• Re-screenshot after every important action.
• Use keyboard shortcuts when they are simpler than pixel hunting.