Skip to content

troubleshooting.md

Latest commit

 

History

History
179 lines (141 loc) · 6.28 KB

troubleshooting.md

File metadata and controls

179 lines (141 loc) · 6.28 KB
Raw

Troubleshooting

Fast diagnostic sequence

Run all patch status checks:

python3 scripts/enable-codex-micro.py status
python3 scripts/repair-codex-native-modules.py status
python3 scripts/enable-codex-hid-runtime.py status

Confirm the app has a new main-process PID after patching:

pgrep -af '^/home/[^/]+/projects/input-linux/codex-desktop-overlay/electron'

Inspect the newest Codex log:

latest_log="$(ls -t ~/.local/state/codex/logs/*/*.log 2>/dev/null | head -1)"
test -n "$latest_log" || {
  echo "No Codex desktop logs found" >&2
  exit 1
}
rg -n -i \
  'CodexMicro|node-hid|HID_hidraw|libusb|dictat|microphone|transcrib|push-to-talk' \
  "$latest_log"

Symptom table

Symptom or log line Meaning Action
No Settings → Codex Micro section Micro renderer gate is still remote-controlled or the app has not detected the device Run scripts/enable-codex-micro.py status; apply the patch and fully restart
Failed to find binding for HID_hidraw Linux native binary exists outside the archive but is absent from the ASAR header Run scripts/repair-codex-native-modules.py repair
libusb-1.0.so.0: cannot open shared object file Native module is indexed correctly; Nix runtime path is incomplete Run scripts/enable-codex-hid-runtime.py enable
HID topology watcher addon not found Optional hot-plug watcher is absent Ignore unless polling/reconnection also fails
The same Electron PID remains after “restart” Only the renderer/window reloaded; the main process still has the old ASAR header/module cache Terminate the overlay Electron processes and relaunch
Device appears in Work Louder Input but not Codex Wrong layer, vendor HID interface access, or Codex service discovery issue Verify Layer 1, udev access, then inspect logs
Mic key changes RGB/UI but produces no text HID and event dispatch work; failure is in microphone capture or transcription Check media permissions, PipeWire, and dictation errors
Everything breaks after an app update The overlay replaced patched assets or changed minified gate counts Do not force the old patch; inspect the new bundle and update match expectations

Force a real restart

Closing the window may leave the warm-start or tray process alive:

pid_file="${XDG_STATE_HOME:-$HOME/.local/state}/codex-desktop/app.pid"
overlay="${CODEX_LINUX_OVERLAY:-$HOME/projects/input-linux/codex-desktop-overlay}"
test -r "$pid_file" || {
  echo "Codex PID file not found: $pid_file" >&2
  exit 1
}
codex_pid="$(cat "$pid_file")"
codex_args="$(ps -p "$codex_pid" -o args=)" || {
  echo "Codex PID is stale: $codex_pid" >&2
  exit 1
}
case "$codex_args" in
  *"$overlay/electron"*) ;;
  *)
    echo "Refusing to terminate unexpected process: $codex_args" >&2
    exit 1
    ;;
esac

printf 'Stopping PID %s: %s\n' "$codex_pid" "$codex_args"
kill -TERM -- "$codex_pid"

# This should produce no output before relaunch.
pgrep -af "$overlay/electron"

Wait until the final command returns nothing, then launch the desktop entry and confirm the main PID changed.

Device access

The tested Micro uses vendor ID 303a and product ID 8360. A typical NixOS udev configuration is:

services.udev.extraRules = ''
  KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="8360", MODE="0660", TAG+="uaccess"
  SUBSYSTEM=="usb", ATTR{idVendor}=="303a", ATTR{idProduct}=="8360", MODE="0660", TAG+="uaccess"
'';

Rebuild the system and reconnect the device after changing udev rules. Confirm that a matching node exists and is readable/writable:

shopt -s nullglob
nodes=(/dev/hidraw*)
((${#nodes[@]})) || {
  echo "No hidraw devices found" >&2
  exit 1
}

matched=false
for node in "${nodes[@]}"; do
  properties="$(udevadm info -q property -n "$node" 2>/dev/null)"
  grep -qx 'ID_VENDOR_ID=303a' <<<"$properties" || continue
  grep -qx 'ID_MODEL_ID=8360' <<<"$properties" || continue
  matched=true
  [[ -r "$node" && -w "$node" ]] &&
    echo "$node: accessible" ||
    echo "$node: permission denied"
done
$matched || {
  echo "No Codex Micro hidraw device found" >&2
  exit 1
}

The investigated Linux setup communicated with the Micro over Bluetooth. That observation should not be generalized into a claim that all Codex Micro USB-C connections are charge-only; the official product page lists USB-C connectivity.

Check the native binary directly

binding=~/projects/input-linux/codex-desktop-overlay/resources/app.asar.unpacked/node_modules/@worklouder/device-kit-oai/node_modules/@worklouder/wl-device-kit/node_modules/node-hid/prebuilds/HID_hidraw-linux-x64/node-napi-v4.node
file "$binding"
ldd "$binding"

The binary should be an x86-64 ELF shared object. In a normal interactive shell, ldd may still show Nix libraries as missing because the overlay launcher builds its own library path. The authoritative check is the fresh app log after scripts/enable-codex-hid-runtime.py and a full restart.

Microphone and PipeWire

If the Micro event starts dictation but audio capture fails:

wpctl status
systemctl --user status pipewire pipewire-pulse wireplumber

The existing local recovery for a stale PipeWire graph is:

systemctl --user restart wireplumber pipewire pipewire-pulse

On the original investigation machine only, the author’s local Parakeet pipeline can be tested independently with:

~/.local/bin/dictation-selftest.sh

That helper is not provided by this repository. Other users should substitute their own microphone/inference self-test. Do not bridge local transcription into Codex until HID press/release and composer focus are proven. That separation keeps device, audio, inference, and insertion failures distinguishable.

Rollback after a partial failure

Each patch refuses partial or surprising backup states. Fully terminate the Electron main process using the verified PID-file sequence above, then return to the original overlay:

python3 scripts/enable-codex-hid-runtime.py restore
python3 scripts/repair-codex-native-modules.py restore
python3 scripts/enable-codex-micro.py restore

Run all three status commands afterward, then relaunch Codex.

If a tool reports that only one member of a backup pair exists, stop and inspect the files manually instead of deleting anything.