Nguyen Cong Hoang

Terminal history and projects

Lightspot reads your zsh history and the recent-project lists of your editors, so the command you ran yesterday and the repository you were working in are a few letters away. It also opens folders in the terminal you prefer and can run admin commands with Touch ID.

Lightspot guide
  1. Overview
  2. Install, update and uninstall
  3. Searching and the app grid
  4. Calculator and conversions
  5. Developer tools
  6. Terminal history and projects
  7. Custom commands, web search and snippets
  8. Browser, clipboard and system
  9. Turning off Apple Spotlight
  10. Menu bar and settings
  11. Privacy
  12. How Lightspot works

zsh history

Type any part of a command you ran before. Matching commands appear under Terminal History, up to six at a time, best matches first and recent commands ahead of old ones. ↵ runs the command in your terminal.

Typing docker lists docker commands from zsh history, with the pinned docker compose up -d as Top Hit
  • Lightspot reads $HISTFILE, $ZDOTDIR/.zsh_history, ~/.zsh_history or ~/.zhistory, whichever exists first. Only zsh is supported; bash history is not read.
  • It reads the last 2 MB of the file and keeps up to 1,200 different commands, removing duplicates and keeping the most recent copy. Commands shorter than 2 or longer than 300 characters are skipped.
  • It understands zsh’s extended history format (with timestamps) and commands split over several lines, which it shows joined with ⏎.
  • The file is read again only when it changes, the next time you open the panel.

A history command needs at least a substring match and is never the Top Hit by chance: only a pinned command, or one you picked before for the same text, can be promoted. Lightspot launched at login usually does not see HISTFILE or ZDOTDIR, because those variables are set by your shell, not by macOS; with a custom location, the file may not be found.

Pinned commands

Select a history command and press ⌘P to pin it, or use the pin button on the row. Pinned commands get a large ranking bonus, show Pinned in their subtitle, can become the Top Hit, and stay searchable even after they drop out of your history file.

Typing terraform: the pinned terraform plan command is the Top Hit, with a project, a browser history page and another command below

Press ⌘⇧P (or choose Pinned Commands… in the menu) to manage them: reorder with the arrow buttons, run one in your terminal, or unpin it with ⌘P. Up to 50 commands can be pinned; new ones go to the top.

The Pinned Commands overlay with four commands and buttons to reorder, run and unpin

Recent projects

Lightspot reads the recent-folder lists that your editors keep and shows matching folders under Recent Projects, with the path and the editor that opened it.

A project row for payments-service opened in GoLand, with Finder and Terminal buttons and the ↵, ⌘↵ and ⌥↵ hints
  • ↵ opens the folder in the editor it came from.
  • ⌘↵ opens the folder in your terminal, ⌥↵ in Finder. The two buttons on the selected row do the same.
EditorRead from
VS Code~/Library/Application Support/Code/User/globalStorage/storage.json
Cursor~/Library/Application Support/Cursor/User/globalStorage/storage.json
Zed~/Library/Application Support/Zed/db.sqlite (read-only)
JetBrains IDEs~/Library/Application Support/JetBrains/<IDE>/options/recentProjects.xml
Android Studio~/Library/Application Support/Google/AndroidStudio<version>/options/recentProjects.xml
Sublime Text~/Library/Application Support/Sublime Text/Local/Session.sublime_session

Only folders that still exist are listed, at most 75 in total, with the most recently used first within each editor; a folder opened in two editors appears once. A project appears once you type two or more letters of its folder name or path. Lightspot rereads a list only when its file changes.

Lightspot recognises these JetBrains-based IDEs by the name of their settings folder and opens each project in the matching app, including early-access builds:

IDENote
IntelliJ IDEA, IntelliJ IDEA CEEither edition, whichever is installed
PyCharm, PyCharm CEEither edition, whichever is installed
WebStorm, GoLand, CLion, RustRover, Rider
PhpStorm, DataGrip, RubyMine, DataSpell
Android Studio, Android Studio PreviewRead from the Google folder

Projects from other JetBrains tools are listed as JetBrains. When the app a project belongs to is not installed, ↵ opens the folder in VS Code if it is installed, or in Finder.

Typing api: the api-gateway project as Top Hit with apps, a bookmark and System Settings below

Choosing a terminal

Choose your terminal in the menu bar icon: Terminal App. The menu lists the ones installed on your Mac; Apple’s Terminal is always there and is the default. Your choice is used to run history and pinned commands, Terminal-type custom commands, and to open project folders.

TerminalRunning a commandOpening a folder
Terminal (default)AppleScript: do scriptOpens the folder in Terminal
iTerm2AppleScript: new window, write textOpens the folder in iTerm2
Ghosttyopen -n -b com.mitchellh.ghostty --args -e <shell> -l -i -c …--working-directory=<folder>
Kittyopen -n -b net.kovidgoyal.kitty --args <shell> -l -i -c …--directory <folder>
WezTermopen -n -b com.github.wez.wezterm --args start -- <shell> -l -i -c …start --cwd <folder>
Alacrittyopen -n -b org.alacritty --args -e <shell> -l -i -c …--working-directory <folder>
WarpRuns in Apple’s Terminal instead (see below)warp://action/new_tab?path=<folder>

Ghostty, Kitty, WezTerm and Alacritty run the command through your login shell (<shell> is the one set for your account, usually zsh) in a new window, which then stays open with a shell. Warp cannot be handed a command to run, so with Warp selected, history, pinned and Terminal-type custom commands run in Apple’s Terminal, while folders still open in Warp. If the chosen terminal has been uninstalled, Lightspot uses Apple’s Terminal. The custom commands manager shows the app that will actually run each command.

Terminal in the current Finder folder

Type terminal here or term here to open your terminal in the folder of the frontmost Finder window, or in the folder selected in it. The row only appears when a Finder window is open. Lightspot asks Finder for the folder through AppleScript, so macOS asks once for permission to let Lightspot control Finder.

Terminal in Finder Folder: Open Terminal in ~/code/lightspot-site

sudo with Touch ID

Some quick actions need administrator rights: Flush DNS Cache (dscacheutil -flushcache; killall -HUP mDNSResponder), Purge Inactive Memory (purge), killing another user’s process, and any custom shell command that contains sudo. Lightspot runs them in one of two ways:

  • If Touch ID for sudo is on, it runs sudo inside a hidden terminal session, so the Touch ID prompt appears and no Terminal window opens. If sudo asks for a password instead, Lightspot stops and falls back to:
  • The standard macOS administrator password dialog.
Flush DNS Cache as the Top Hit for flush dns

Type touch id or sudo to find Toggle Touch ID for Sudo. Its subtitle says whether Touch ID for sudo is on. Pressing ↵ (after your password) turns it on or off for every terminal on the Mac, not only for Lightspot, by editing /etc/pam.d/sudo_local, Apple’s file for local sudo settings that survives macOS updates:

  • On: uncomments or adds the line auth sufficient pam_tid.so, creating the file from Apple’s sudo_local.template when it does not exist.
  • Off: comments that line out again.
Typing touch id: the Touch ID settings pane and the Toggle Touch ID for Sudo action, currently enabled