Skip to content
Lanterna

Usage

Basic operation, filtering, window actions, links, and troubleshooting

  1. 01 Hold⌘Keep holding Cmd
  2. 02 StepTab× nPress Tab for the next window
  3. 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.
  1. 01 Open⌘SpaceOpen in filter mode
  2. 02 TypeA–ZType to narrow the list
  3. 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.
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.
esc Clears what you typed. With nothing typed, closes the switcher.

Filter input also matches romaji. For example, gijiroku matches ぎじろく and 議事録. Kana readings work with the bundled tables. Kanji readings need a dictionary.

To match kanji readings, place a migemo-dict file next to the config file and relaunch Lanterna.

Terminal window
curl -L -o SKK-JISYO.L https://raw.githubusercontent.com/skk-dev/dict/master/SKK-JISYO.L
curl -L -o skk2migemo.sh https://raw.githubusercontent.com/peacock0803sz/Lanterna/main/scripts/skk2migemo.sh
bash skk2migemo.sh SKK-JISYO.L ~/Library/Application\ Support/Lanterna/migemo-dict

SKK 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.

While the switcher is up, hold Cmd 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.

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 the Show windows of setting in the Filter 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 Filter 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. 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.

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. 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.

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
Next ↓
Previous ↑
Commit ↩, keypad Enter
Cancel esc, ⌘.
Toggle active app only ⌘/
Delete backward ⌫
Clear query esc
Close window ⌘W
Quit application ⌘Q
Hide application ⌘H
Minimize window ⌘M
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 and Toggle active app only would fire while typing, so every key for those needs Cmd, Ctrl, or Opt. 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.

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.

Terminal window
pgrep -x Lanterna # expect no output; run `pkill Lanterna` first if there is any

Then start Lanterna again and stop it cleanly, so its shutdown restores the shortcuts.

Terminal window
/Applications/Lanterna.app/Contents/MacOS/Lanterna &
sleep 1
pkill Lanterna

If the shortcuts are still off after that, log out and back in. The system’s assignment is per login session.

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.