Hermes-Relay Doctor

Runs a sequential smoke-test of the full bridge stack and reports pass/fail with fix hints for each check. Use this before reaching for android_* tools when something feels off.

When to Use

• User runs /hermes-relay-doctor.
• User says the bridge isn't working, the phone isn't connecting, or a screenshot is failing.
• You want to verify the stack is healthy before issuing android_* tool calls.
• The android_ping() tool returns an error or phone_connected: false.

Procedure

Run the plugin CLI:

hermes relay doctor        # host CLI (plugin enabled in Hermes)
hermes-relay doctor        # shell shim (installed by install.sh → plugin.cli)

If neither is available (plugin not enabled, or the hermes-relay shim was never installed), run the checks inline:

PORT="${RELAY_PORT:-8767}"
curl -sf "http://127.0.0.1:$PORT/health"
curl -sf "http://127.0.0.1:$PORT/bridge/status"
curl -sf "http://127.0.0.1:$PORT/ping"
curl -sf "http://127.0.0.1:$PORT/current_app"
curl -sf "http://127.0.0.1:$PORT/screen"
curl -sf "http://127.0.0.1:$PORT/screenshot"

All six checks call loopback (127.0.0.1) — no bearer token needed.

Interpreting Results

Screenshot gap (known issue)

/screenshot returns 500 {"error":"MediaProjection not granted — enable Bridge screenshots in the app"} when the accessibility service is running but the system MediaProjection consent dialog hasn't been accepted.

Fix:

1. Open the Hermes-Relay app → Bridge screen.
2. Toggle the Allow Agent Control switch on.
3. Android shows a "Start recording?" system dialog — tap Start.
4. Re-run /hermes-relay-doctor to confirm the screenshot check passes.

This is a per-boot requirement on Android — the MediaProjection grant is revoked on reboot.

Re-running after a fix

hermes relay doctor

If the hermes-relay shim is missing, refresh it (and the rest of the install) with the idempotent updater:

hermes-relay-update

Or re-run the full installer:

curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash