Usage
Basic operation, filtering, window actions, links, and troubleshooting
Basic operation
Section titled “Basic operation”- 01 Hold⌘Keep holding Cmd
- 02 StepTab× nPress Tab for the next window
- 03 Release⌘Release Cmd to switch
| ⌘Tab | Shows the switcher. Keep holding Cmd and press Tab to move, then release Cmd to switch. |
| ⇧⌘Tab | Moves in the reverse direction. |
| ⌥Tab | Shows the parallel switcher: the same panel with its own settings, starting on the front app’s windows alone. Keep holding Opt to move, then release Opt to switch. |
| ⇧⌥Tab | Moves the parallel switcher in the reverse direction. |
| ⌘J/N | Moves to the next row, like ↓. |
| ⌘K/P | Moves to the previous row, like ↑. |
| ⌘S | Switches the open switcher to filter mode. |
| ⌘/⌥, | Closes the switcher and opens Settings. |
Parallel switcher
Section titled “Parallel switcher”Opt+Tab opens a second switcher beside Cmd+Tab: the same panel and the same keys, but with its own settings. Out of the box it lists only the front app’s windows, so you can hop between one app’s windows without pressing Cmd+/ first. Cmd+Tab keeps listing every app’s windows. Letting go of Opt switches, the way letting go of Cmd does on the main switcher.
The Switchers tab of Settings holds one sub-tab per switcher, Cmd+Tab and Opt+Tab, with the same rows in each: which apps’ windows to list, how to treat windows on other Spaces, hidden apps, minimized and fullscreen windows, and apps without windows, and where those kinds go when the list is grouped. Each Opt+Tab row is linked to Cmd+Tab and follows it until you unlink it, except Show windows of, which starts unlinked on Active app; Link all to Cmd+Tab links every row again. Everything else, such as the sort order, fuzzy matching, how the list groups, the panel’s display, width, and text size, the show delay, and the gestures inside the panel, is shared by both switchers and stays in its own tab. Switching the parallel switcher off hands Opt+Tab and Shift+Opt+Tab back to the front application; switching it back on answers them again without a restart.
The config file writes the two switchers side by side under switchers, with main for Cmd+Tab and parallel for the parallel switcher. A parallel row reads "inherit" to follow the main switcher. Shared settings belong at the top level; written under main or parallel they are ignored with a diagnostics entry:
{ "switchers": { "main": { "windowScope": "allApps" }, "parallel": { "windowScope": "inherit", "minimizedMode": "show", "enabled": false } }}Without a switchers section the file reads as before, and the parallel switcher lists the front app’s windows alone.
Filtering
Section titled “Filtering”- 01 Open⌘SpaceOpen in filter mode
- 02 TypeA–ZType to narrow the list
- 03 Switch↩Switch to the chosen window
| ⌘Space | Shows the switcher in filter mode. In this mode, releasing Cmd does not close it. Pressing it in a switcher opened with Cmd+Tab switches that switcher to filter mode, and so does S. |
| A–Z | Keeps only the rows whose app name or window title contains what you typed. Case is ignored. |
| ↑↓ | Moves the selection. |
| ↩ | Switches to the chosen window. |
| ⌫ | Deletes one character. |
| ←→, CtrlB/F | Moves the insertion point one character. |
| CtrlA/E | Jumps to the start or the end. |
| CtrlH | Deletes one character, like ⌫. |
| fn+⌫, CtrlD | Deletes the next character. |
| CtrlW | Deletes one word. |
| CtrlU/K | Deletes back to the start or forward to the end. |
| CtrlN/P | Moves the selection, like ↓/↑. |
| CtrlM | Switches to the chosen window, like ↩. |
| CtrlG | Closes the switcher at once, keeping what you typed. |
| esc | Clears what you typed. With nothing typed, closes the switcher. |
A Ctrl letter with no row above types nothing while filtering: it is dropped.
Romaji input
Section titled “Romaji input”Filter input also matches romaji. For example, gijiroku matches ぎじろく and 議事録. Kana readings work with the bundled tables. Kanji readings need a dictionary.
Kanji dictionary from SKK
Section titled “Kanji dictionary from SKK”To match kanji readings, place a migemo-dict file next to the config file and relaunch Lanterna.
curl -L -o SKK-JISYO.L https://raw.githubusercontent.com/skk-dev/dict/master/SKK-JISYO.Lcurl -L -o skk2migemo.sh https://raw.githubusercontent.com/peacock0803sz/Lanterna/main/scripts/skk2migemo.shbash skk2migemo.sh SKK-JISYO.L ~/Library/Application\ Support/Lanterna/migemo-dictSKK dictionaries ship in EUC-JP, so the script converts the output to UTF-8. Entries with okurigana are out of scope, /-separated candidates become tab-separated words, and annotations after ; are dropped, keeping bare kanji only. With a repo checkout, use scripts/skk2migemo.sh directly.
Force keyboard input source
Section titled “Force keyboard input source”Lanterna reads the panel’s keys before any input method does, so typing a query never goes through the IME. Tools that rewrite keys based on the selected input source still do, though. A Karabiner-Elements thumb-shift rule active only for a Japanese source, for example, turns abc into something else before Lanterna sees it.
To avoid that, choose a source under Force keyboard in the Filter settings, or set "forcedInputSource" to its ID in config.json, such as "com.apple.keylayout.ABC". Lanterna selects that source while the switcher is up and gives yours back when it closes or when Lanterna quits. If the switcher closes on a different source you picked by hand, that source stays. Absent means off.
Window actions
Section titled “Window actions”While the switcher is up, hold Cmd or Opt and press one of these keys to act on the chosen row. The switcher stays up and the list updates in place.
| ⌘/⌥W | Closes the window. |
| ⌘/⌥Q | Quits the app. |
| ⌘/⌥H | Hides the app. |
| ⌘/⌥M | Minimizes the window. |
By default, hidden apps and minimized windows move below the other windows, grouped under headings such as HIDDEN APPS and MINIMIZED. If an action fails, the list goes back to how it was and a short note appears. You cannot act on Lanterna’s own row. On the row of an app with no open window, closing and minimizing have nothing to act on and say so, while quitting and hiding act on the app.
Narrowing and grouping the list
Section titled “Narrowing and grouping the list”Press ⌘/ while the switcher is up to list only the windows of the app that was in front when it opened. A band above the list names that app, the query stays as typed, and pressing the key again brings every app back. The next time the switcher opens it starts on its Show windows of setting in the Switchers tab, which can make Active app the starting point.
Apps that are running with no open window can be listed as rows of their own, reading “No open windows”. Choosing one brings the app forward. Apps without windows in the Switchers tab shows them, hides them, or keeps them below the other windows under APPS WITHOUT WINDOWS. Hidden is the default, and a query naming such an app still finds it.
The Groups tab can group the list:
- By Space puts the windows of each Space under a heading naming the desktop, and the display when there is more than one. Spaces in view come first. Windows on another Space join their own group instead of a section below.
- Manually lets you choose up to nine groups and assign apps to them by bundle ID, either from the running apps or by typing the ID. Headings show the group number, a name you give the group, or the names of the apps in it. Apps you have not assigned join the first group.
When the list is grouped, each kind of section below the windows, such as MINIMIZED, can go at the end of the list or inside each group, under Placement when grouped in the Switchers tab. By Space is the exception for two kinds: apps without windows always go after the last group, since they are on no Space, and the setting for windows on another Space does not apply, since those windows join their own group. A list with only one group shows no heading.
Panel display and width
Section titled “Panel display and width”Show Panel on in the Appearance tab chooses which display the panel opens on: the Primary display, the Display with cursor, the Display with focused window, or All displays. Primary, the display with the menu bar, is the default. With All displays the same list appears on every display, and the panel on the cursor display takes the keyboard. A choice takes effect the next time the panel opens.
Panel Width in the same tab scales the panel from Narrow to Wide in five steps. The middle step is the standard width. A new width takes effect the next time the panel opens, and a width that would overflow a display is fitted inside it.
Show delay in the same tab waits before showing the panel, from 0 to 1000 milliseconds in steps of 50. At 0, shown as Off, the panel appears at once as before. With a wait set, letting go before it runs out switches without showing anything, and holding on opens the panel as usual. A new wait takes effect the next time the panel opens.
Hover to select in the same tab moves the selection to the row under the pointer. Off by default; the choice follows the pointer once it is on. The panel never moves under a pointer that has not moved since it opened. Scroll to select moves the selection by scrolling instead of scrolling the view, and the view follows the selection. Off by default. Clicking a row picks it and switches to it with either switch off or on. Number jump in the same tab jumps to a row by its number: hold left or right Command or Option, press the digits in order, and let go to switch. When both Command and Option are held, a Cmd+Tab panel switches on releasing Command, and an Opt+Tab panel switches on releasing whichever of the two goes up last. Row numbers show while the modifier is held. Off by default. Row numbers names which rows numbers cover: window rows alone, or every row. Reorder rows in the same tab moves the selected row with Shift and arrow keys inside grouped lists, keeping the order across restarts. Off by default. Auto-focus single match in the same tab focuses that row and closes the panel when filtering narrows the list to one row, after a short pause. On by default (autoFocusSingleCandidate).
App icon badges in the same tab draws each app’s Dock badge, such as an unread count, on the icon of every row that app has, window rows and rows of apps without windows alike. Off by default. The badges are read from the Dock as the panel opens, and a badge that changes while the panel is open shows the next time it opens. Counts above 999 read 999+. Copies of one app launched from the same place show no badge, because the Dock does not say which copy each icon belongs to. Lanterna reads the badges with the Accessibility permission it already has and asks for no other. In the config file the switch is appIconBadges; it is optional and reads as off when absent.
Switching to apps and windows
Section titled “Switching to apps and windows”The General tab holds two switches under Switching, both off by default. A change takes effect the next time you switch to an app or window, without a restart.
Open a window when switching to an app that has none does what clicking the app’s Dock icon does: the app opens a window, unhides itself, or does nothing, as the app decides. Lanterna never checks which of those happened.
Bring only the chosen window forward tries to keep the application’s other windows where they were on every display when a window row is switched to. It is a workaround for macOS bringing another window of the same application forward along with the chosen one. Even with it on, the other windows may briefly come forward before settling back. If switching looks wrong with it on, please open a bug report using the Bug report template.
In the config file the two switches are reopenWindowlessApps and raiseOnlyChosenWindow. Both are optional and read as off when absent.
Customizing keybindings
Section titled “Customizing keybindings”Every keybinding below can be changed through the keybindings section of the config file or the Keyboard tab of Settings. Keys are physical positions, so they work the same under any input source.
| Action | Default keys |
|---|---|
| Show | ⌘Tab |
| Show in reverse | ⇧⌘Tab |
| Show for filtering | ⌘Space |
| Show parallel | ⌥Tab |
| Show parallel in reverse | ⇧⌥Tab |
| Next | ↓, J, N, CtrlN |
| Previous | ↑, K, P, CtrlP |
| Commit | ↩, keypad Enter, CtrlM |
| Cancel | esc, ⌘., CtrlG |
| Toggle active app only | ⌘/ |
| Move cursor left | ←, CtrlB |
| Move cursor right | →, CtrlF |
| Move cursor to start | CtrlA |
| Move cursor to end | CtrlE |
| Delete backward | ⌫, CtrlH |
| Delete forward | fn+⌫, CtrlD |
| Delete word backward | CtrlW |
| Delete to start | CtrlU |
| Delete to end | CtrlK |
| Clear query | esc |
| Close window | ⌘/⌥W |
| Quit application | ⌘/⌥Q |
| Hide application | ⌘/⌥H |
| Minimize window | ⌘/⌥M |
| Start filtering | S |
| Open settings | ⌘/⌥, |
| Jump to row number | ⌘/⌥ digits |
| Move row up | ⇧⌘/⌥↑ |
| Move row down | ⇧⌘/⌥↓ |
Show, Show in reverse, and Show for filtering reach across the system, and the window actions, Toggle active app only and Open settings would fire while typing, so every key for those needs Cmd, Ctrl, or Opt. The two parallel invocations need Cmd or Opt: a key holding neither leaves no release to switch on. Jump to row number, Move row up and Move row down also need Cmd, Ctrl, or Opt. Letter and number keys with no modifier act only while not filtering; while filtering they type into the query. A Ctrl key with no binding types nothing while filtering. Where bindings ask for the same count of modifiers, the one asking for Ctrl answers first. A key already used by another action is refused, except that Clear query and Cancel may share keys. An action left with no keys falls back to its defaults, but if the defaults are also taken the action can stay unbound with a diagnostics entry. Invocation changes apply at once.
- RepoGitHub repositorygithub.com/peacock0803sz/Lanterna
- ReleasesReleases…/Lanterna/releases
- LicenseLICENSE…/blob/main/LICENSE
- ContributingCONTRIBUTING…/blob/main/CONTRIBUTING.md
Troubleshooting
Section titled “Troubleshooting”Cmd+Tab shortcuts are not restored after a crash
Section titled “Cmd+Tab shortcuts are not restored after a crash”Lanterna takes Cmd+Tab and Shift+Cmd+Tab away from the system while it runs and gives them back when it exits. After kill -9 or a crash it cannot give them back, so both shortcuts stay off until something else restores them.
Check that no Lanterna is running before doing anything else. Restoring turns the shortcuts back on without reading their current state, so running this while another Lanterna is up takes the shortcuts away from that process. Running more than one at a time is not supported.
pgrep -x Lanterna # expect no output; run `pkill Lanterna` first if there is anyThen start Lanterna again and stop it cleanly, so its shutdown restores the shortcuts.
/Applications/Lanterna.app/Contents/MacOS/Lanterna &sleep 1pkill LanternaIf the shortcuts are still off after that, log out and back in. The system’s assignment is per login session.
Windows do not appear
Section titled “Windows do not appear”Check that Accessibility and Input Monitoring are granted (see the Guide), then relaunch Lanterna.
If these steps do not fix the problem, please open a bug report using the Bug report template.