troubleshooting.md

Troubleshooting

Most problems show up in the menu bar first. Click the hat: the first line of its menu says what XCommander is doing right now.

Nothing happens when I press the leader

Check, in order:

  1. Is Xcode the app in front? XCommander only listens while Xcode is frontmost. The hat's menu says Ready when it is.
  2. Is there a warning sign on the hat? XCommander needs Accessibility permission. Choose Open Accessibility Settings… in its menu and turn XCommander on. If it's already on, turn it off and on again.
  3. Is there a lock on the hat? Another app has turned on secure input: a password field somewhere, or Secure Keyboard Entry in Terminal or iTerm. While it's on, macOS hides keystrokes from every app. Close the password field or turn the option off.
  4. Is it switched off? Leader Key in the hat's menu must be ticked (the same switch as Settings → General → Enabled while Xcode is frontmost).
  5. Is the leader taken? If you changed it to ⌃SPC or ⌥SPC, another app (an input-source switcher, Alfred, Raycast) may get the key first. Try the default, ⌥RET.

A key beeps, or a command is missing

  • A beep means Xcode has that command but it's greyed out right now, as it would be in the menu: debugger commands need something running, editor commands need an editor in front. Right after an update, Xcode opens on its Welcome window, where most menus are missing: open a project first.
  • A key missing from the panel means your version of Xcode doesn't have that command at all, so XCommander hides it rather than show a key that can't work.
  • Settings → Diagnostics → Check keymap, or ⌥↩ h c, checks every key against your Xcode's menus and lists anything that no longer finds its command.
  • If Xcode was just updated, ⌥↩ q r makes XCommander re-read its menus.

The permission prompt keeps coming back

macOS ties the Accessibility permission to the app's signature. This happens when there are two copies of XCommander, for example one downloaded and one built from source: each is a different app to macOS.

  1. Quit every copy of XCommander.
  2. In System Settings → Privacy & Security → Accessibility, remove every XCommander entry with the – button.
  3. Keep only one copy, open it, and grant permission once.

Updates installed from inside XCommander keep the permission: they're signed the same way.

macOS won't open XCommander

If macOS says it can't verify XCommander, or that it may be malware, the file didn't come from an official release, or it was damaged on the way. Delete it and download it again from the releases page. Each release lists a SHA-256 checksum if you want to check the download:

shasum -a 256 ~/Downloads/XCommander.dmg

My configuration file doesn't apply

  • Check the path: ~/.config/xcommander/config.toml, or .xcommander.toml in the project's root folder.
  • The first line must be version = 1.
  • Settings → Diagnostics → Check config shows what the last load said. From Terminal, --check prints every problem with its line number (see Configuration).
  • If the file has an error, XCommander keeps the last version that worked, so a fix applies as soon as you save it.

Updates

  • Check for Updates… in the menu checks straight away.
  • The daily check can be turned off in Settings → General.
  • If an update fails to install, download the latest version from the releases page and replace the app in Applications. Your settings and permission stay.

Logs

XCommander writes what it's doing to the macOS log. To watch it live, run this in Terminal, then reproduce the problem:

/usr/bin/log stream --level info --predicate 'subsystem == "dev.xcommander.XCommander"'

To see the last ten minutes instead:

/usr/bin/log show --last 10m --info --predicate 'subsystem == "dev.xcommander.XCommander"'

Type the full /usr/bin/log: in zsh, macOS's default shell, a plain log is a different, built-in command.

The log never contains what you type in your code: XCommander only logs its own keys and commands.

Reporting a bug

Report a Bug… in the menu opens a form on GitHub with your XCommander, Xcode and macOS versions already filled in. The most useful reports say what you pressed, what you expected, and what happened instead, and include a few lines of the log above. Ideas are welcome too, on the same issues page.