--- title: 'Getting started' url: 'https://xcommander.dev/docs/getting-started' markdown: 'https://xcommander.dev/docs/getting-started.md' date: '2026-11-09' description: "By the end of this page XCommander will be installed, it will have the one permission it needs, and you'll have built your project without touching the mouse or the menus. What you need macOS 14 (Sonoma) or later. Xcode 27 or later. XCommander reads Xcode's menus as they are on your Mac, and it's …" --- getting-started.md # Getting started By the end of this page XCommander will be installed, it will have the one permission it needs, and you'll have built your project without touching the mouse or the menus. ## What you need - **macOS 14** (Sonoma) or later. - **Xcode 27** or later. XCommander reads Xcode's menus as they are on your Mac, and it's tested against Xcode 27. - Optional: [ripgrep](https://github.com/BurntSushi/ripgrep), for project-wide search with a live preview. With [Homebrew](https://brew.sh): `brew install ripgrep`. Without it, search falls back to Xcode's own Find navigator. ## Install 1. Download `XCommander.dmg` from the [releases page](https://github.com/XCommanderDev/XCommander/releases). The newest release is at the top. 2. Open the DMG and drag **XCommander** onto the **Applications** folder next to it. 3. Open XCommander from Applications. macOS asks whether you want to open an app downloaded from the internet: click **Open**. XCommander has no Dock icon and no main window. It lives in the menu bar, as a small hat. Note Official builds are signed with my Developer ID and notarized by Apple, so macOS knows where they come from. If macOS ever says it *can't verify* XCommander or that it may contain malware, don't open it: download it again from the releases page above. ## Grant Accessibility The first time it opens, XCommander shows a short window explaining what it needs and why. Click **Continue**, and macOS asks for **Accessibility** permission. That system prompt is blunt: it says XCommander wants to control your computer. That's fair, because the permission really is that broad. It's the only way an app can see a keystroke and press a menu item for you. Here is everything XCommander does with it: - it watches for **one key**, the leader, and only while Xcode is the app in front; - it reads Xcode's menus, and presses the item you choose; - nothing else. There are no analytics. Its only network connection is a daily check for updates, which you can turn off. To grant it: 1. In the prompt, click **Open System Settings**. 2. In **Privacy & Security → Accessibility**, turn on **XCommander**. 3. Come back to Xcode. There's no need to restart anything. If you click *Not Now*, or the switch gets turned off later, the hat in the menu bar shows a warning sign, and its menu has **Open Accessibility Settings…** to take you straight there. ## Your first command Open a project in Xcode, click into the code editor, and: 1. Press ⌥↩ (hold Option, press Return) and **let go**. 2. Wait a moment. A panel appears at the bottom of Xcode's window, listing letters and what they do. This is the **which-key panel**. 3. Press m. The panel changes: you're now in the **make** group. 4. Press m again. Xcode builds your project. That's the whole idea. ⌥↩ m m is *leader, make, make*. Every command is a short sequence like this, and the letters are chosen to be easy to remember: m for **make**, c for **code**, g for **git**, w for **windows**. A few things you'll notice: - **You don't have to wait for the panel.** It only appears if you pause. Once your fingers know a sequence, type it straight through and the panel never shows. - **Esc cancels**, at any point. So does doing nothing for ten seconds, or switching to another app. - **A wrong key is swallowed**, not typed into your code. While a sequence is in progress, nothing you press reaches the editor. - **Outside Xcode, XCommander does nothing.** In every other app, ⌥↩ behaves exactly as it always has. ## Reading the which-key panel Each line of the panel is a key and what it does: - a **purple name starting with +** is a group: press the key to see what's inside; - a **plain name** is a command: press the key to run it; - a **dimmed shortcut** on the right is Xcode's own keyboard shortcut for the same command, when it has one. The panel teaches you Xcode's shortcuts too. The panel only lists commands your version of Xcode has: if it doesn't have one, the key isn't shown. A command that exists but can't run right now (a debugger command with nothing running, say) is still listed, and pressing it just beeps, like clicking a greyed-out menu item. ## The menu bar hat The hat tells you XCommander's state at a glance. Click it to see the state in words: | State | What it means | |---|---| | **Ready** | Xcode is in front and the leader works. | | **Waiting for Xcode** | Another app is in front. XCommander is idle. | | Warning sign | It needs Accessibility permission (see above), or this version of Xcode isn't supported. | | Lock | Another app has turned on *secure input* (a password field, or a terminal's Secure Keyboard Entry). macOS hides keystrokes from every app while it's on, so XCommander pauses until it's off. | | **Leader key disabled** | You switched the leader off, with **Leader Key** in this menu or in Settings. | The menu also shows which version you're running, and has **Leader Key** (tick it off to pause XCommander without quitting), **Settings…**, **Check for Updates…**, **Report a Bug…** and **Quit**. ## Settings **Settings…** in the menu has three tabs: - **General**: which key is the leader (see [Configuration](https://xcommander.dev/docs/configuration) for the choices and what each one hides), whether XCommander is enabled, the search preview, launch at login, and the daily update check. - **Timing**: how long to wait before the which-key panel appears (0.35 s by default) and how long an unfinished sequence waits before giving up (10 s). - **Diagnostics**: check that every key in the keymap still finds its menu item in your Xcode, re-read Xcode's menus, and check your configuration file. Useful before reporting a bug. ## Updates XCommander checks for a new version once a day. When there is one, a line appears at the top of its menu, **Update Available…**, so no window pops up while you're typing in Xcode. (If the check happens just after you open XCommander, it shows the update window straight away.) Click the line to read what changed and install it: XCommander replaces itself and relaunches, and your permission carries over. You can also check at any time with **Check for Updates…**, or turn the daily check off in Settings. If you're running an alpha or beta, you're offered newer alphas and betas as well as final releases. Everyone else is only offered final releases. ## What to expect from an alpha - **Bugs.** Some commands may not work in every situation. Please report them: **Report a Bug…** fills in your XCommander, Xcode and macOS versions. - **Keys that change.** The keymap is still settling. Release notes say when a key moves. - **Xcode updates are handled.** When Xcode updates, XCommander re-reads its menus. If Apple moved or removed something you use, the menu tells you what changed. ## Uninstall 1. Quit XCommander: ⌥↩ q q in Xcode, or **Quit** in its menu. 2. Drag XCommander from Applications to the Trash. 3. In **System Settings → Privacy & Security → Accessibility**, select XCommander and remove it with the **–** button. 4. Optionally, delete your configuration in `~/.config/xcommander`, and the settings with `defaults delete dev.xcommander.XCommander` in Terminal. Next: [Everyday use](https://xcommander.dev/docs/everyday-use), a tour of the commands worth learning first. --- ## Navigation - Parent: [Documentation](https://xcommander.dev/docs.md) - Next: [Everyday use](https://xcommander.dev/docs/everyday-use.md)