Look - Keyboard-First Launcher#

Look Github Repository

Look is a keyboard-first, local-first launcher for macOS, Windows, and Linux. It provides instant access to apps, files, folders, and system settings without leaving the keyboard.

Try it live#

Type in the launcher below - fuzzy search, a"/f"/d"/r" prefixes, and inline calc all work, right in your browser. Press Ctrl+/ for command mode (calc, pomodoro, todo, kill, shell, sys) or Ctrl+, to try Appearance settings. This is a simplified, offline playground - the real Look is faster and does much more. Open the full-screen demo for more room.

Why Look?#

If you're tired of slow launchers or expensive tools like Raycast, Look offers a free, lightweight alternative that stays out of your way. It's designed for developers and power users who want quick access to everything on their machine without leaving the keyboard.

Core Concepts#

• Local-first indexing: All search indexing happens locally on your machine
• SwiftUI (macOS) + Tauri v2 (Windows/Linux): Native UI shells powered by efficient Rust search
• Bounded query-time scoring: Typical search under 1 ms on a 2000-item index
• Usage-aware ranking: Results improve over time based on your usage patterns
• Minimal permissions: No Accessibility, Full Disk Access, or Screen Recording required

Key Features#

• Fast Local Search: Instantly search apps, files, folders, and system settings
• Query Prefixes: Use prefixes like a", f", d", r", rc" to narrow search scope
• Path-like queries: Type git/project/readme for path-biased matches
• Inline calculator: Type 2^10, 4!, 200*15%, sqrt(2) - no mode switch needed
• Web answers (optional): Ask a question or type an entity that isn't indexed locally and get an inline answer card (Wikipedia, DuckDuckGo, currency, weather, crypto) plus web search suggestions
• Daily todo tracker: :todo groups tasks by day with overdue badges, a done-today stat, and a Stats page (streak, 30-day trend, year heatmap)
• Recent files browser: rc" lists what you recently opened and what recently landed on disk, newest first
• Port-based kill: Command mode kill :3000 force-quits whatever owns the port
• Clipboard History: Access recent clipboard items with c"
• Translation: Quick translation with t" and dictionary lookup with tw"
• Command Mode: Built-in calculator, pomodoro timer, todo, force quit, shell commands, and system info
• Floating Layout: Optional inner gaps split the launcher into floating tiles, tiling-WM style
• Customizable Themes: Multiple built-in themes including Catppuccin, Tokyo Night, and more
• Privacy-First: No account, no telemetry, network only on explicit or opt-out actions

Installation#

macOS#

Requirements: macOS 15.0+

brew tap kunkka19xx/tap
brew install --cask look

Then bind Cmd+Space to Look - disable Spotlight's shortcut in System Settings → Keyboard → Keyboard Shortcuts... → Spotlight.

Update:

brew upgrade --cask kunkka19xx/tap/look

curl -fsSL https://raw.githubusercontent.com/kunkka19xx/look/main/scripts/install-look.sh | bash

curl -fsSL https://raw.githubusercontent.com/kunkka19xx/look/main/scripts/install-look.sh | bash -s -- --version <version> --repo kunkka19xx/look

Linux#

Arch Linux (AUR):

yay -S look-bin
# or
paru -S look-bin

Or without an AUR helper:

git clone https://aur.archlinux.org/look-bin.git
cd look-bin
makepkg -si

Ubuntu/Debian:

curl -fsSL https://raw.githubusercontent.com/kunkka19xx/look/main/scripts/linux/install-look.sh | bash

Or download the .deb manually from Releases and run sudo dpkg -i Look_*.deb.

Any distro (AppImage):

chmod +x Look_*.AppImage
./Look_*.AppImage

NixOS (flake):

nix run github:kunkka19xx/look?dir=apps/linows
# or install to profile
nix profile install github:kunkka19xx/look?dir=apps/linows

Pre-built binaries are served via Cachix. For declarative NixOS install, see the README.

Windows#

iex "& { $(irm https://raw.githubusercontent.com/kunkka19xx/look/main/scripts/windows/install-look.ps1) }"

SmartScreen may warn on first run - click "More info → Run anyway". The launcher's global hotkey is Alt+Space (not user-configurable yet; if it conflicts with another app, remap that app instead).

First Launch#

After installing, launch with lookapp from a terminal, or search "Look" in your app launcher / Start menu. On first run, Look indexes your apps, files, and folders in the background - results appear as indexing completes.

Window manager users (i3, sway, Hyprland): Add Look to your WM config manually - see the README for examples.

GNOME desktops: Log out and log back in after the first install so the GNOME Shell extension (for window focusing on Wayland) can load.

Uninstall#

# macOS
brew uninstall --cask look

# Arch
yay -R look-bin

# Ubuntu/Debian
sudo dpkg -r lookapp

# Windows
iex "& { $(irm https://raw.githubusercontent.com/kunkka19xx/look/main/scripts/windows/install-look.ps1) } -Uninstall"

Remove local state (optional):

# macOS
rm -f ~/.look.config && rm -rf ~/Library/Application\ Support/look

# Linux
rm -f ~/.look.config && rm -rf ~/.local/share/look

Permissions#

Look is designed to need as few permissions as possible:

• No Accessibility permission required (macOS)
• No Full Disk Access required - Look indexes standard user directories. Add extras via file_scan_extra_roots in ~/.look.config.
• No Screen Recording required (macOS)
• Network access is used only for explicit actions (t" translation, tw" dictionary lookup, Cmd/Ctrl+Enter web search) and the optional web answers feature, which you can turn off with ai_enabled=false

Getting Started#

Basic Usage#

1. Open Look: Press Cmd+Space (macOS) or Alt+Space (Windows/Linux)
2. Type to Search: Start typing to search apps, files, folders, or settings
3. Navigate: Use Tab/Shift+Tab or arrow keys to move between results
4. Open: Press Enter to open the selected item

Query Prefixes#

Use these prefixes to narrow your search scope. Not sure which to use? Type a single " to open a menu of every prefix with a description, then pick one (click or ↑/↓ then Enter) to drop it into the search field.

Apps only search example#

Directories only search example#

Path-like queries (e.g., git/project/readme) are also supported and bias toward path matches.

Quick calc, convert, and kill#

No need to enter command mode for simple math - Look evaluates inline:

• 2^10 → 1024
• 200*15% → 30 (percent shorthand)
• sqrt(2) → 1.4142

Currency conversion works inline too when web answers are on: 100 usd to eur returns a live answer card. You can also kill a process by port from command mode (Cmd/Ctrl+/), e.g. kill :3000. See Features → Command Mode for the full calc grammar and kill options.

Ask a Question#

With web answers enabled (the default), a question or an entity that isn't indexed locally (e.g. sir alex ferguson) shows an inline answer card sourced from DuckDuckGo/Wikipedia, alongside web search suggestions. Prefix queries never trigger web lookups. See Features for details, or turn it off in Settings → Advanced.

Query Aliases#

Define aliases in ~/.look.config to map search terms to related apps, e.g. alias_note=Notion|Obsidian|Apple Notes. See Configuration → Search Aliases for the full syntax and behavior.

Keyboard Shortcuts#

Global Shortcuts#

Navigation#

Actions#

On Windows/Linux, replace Cmd with Ctrl for all shortcuts below.

Command Mode#

Cmd+1..Cmd+6 switch command panels only while command mode is open. On the home screen these keys go to the running-apps switcher (see below).

Running Apps Switcher#

Available on macOS, Linux, and Windows. The modifier is platform-native: Cmd on macOS, Alt on Linux/Windows.

When enabled, running-app icons appear in the right half of the search bar. On the home screen, Cmd/Alt+the digit shown on each icon's corner badge activates that running app.

Toggle on/off via Settings → Appearance → Running Apps. Turning it off hides the row and disables the digit-switching shortcut; the search bar then spans the full width.

Settings Panel Zoom#

Query Prefixes#

Type a single " to browse all prefixes in an interactive menu, then pick one to drop it into the search field. The full prefix table lives in Getting Started.

Features#

Copy File or Folder (`Cmd/Ctrl+C`)#

With a file or folder selected, press Cmd+C (macOS) or Ctrl+C (Windows/Linux) to copy it to the clipboard.

• Paste into a file manager, Mail, Slack, or any app that accepts files → pastes the actual file/folder
• Paste into a text editor or terminal → pastes the path as a string
• Works on results of kind file and folder; apps use Enter or Cmd/Ctrl+F instead

Multi-Pick Files/Folders (`Cmd/Ctrl+P`)#

Build up a set of files/folders, then paste or open them anywhere in one go.

• Cmd+P on a focused file or folder toggles it in or out of the picked set; every toggle rewrites the system pasteboard with all picked items.
• The right panel switches to a Picked (N) list while the set is non-empty: each row has an X to remove a single item, plus a Clear all button.
• Shift+Enter (or the Open all button) opens every picked item at once.
• Cmd+Shift+P clears the entire picked set and the pasteboard.
• Paste behavior matches Cmd+C - into Finder/Mail/etc. you get the actual files; into a text field you get the paths.

Move to Trash (`Cmd/Ctrl+D`)#

Delete files without leaving the launcher:

• Cmd+D moves the selected file/folder (or the whole picked set, if any) to the system trash and refreshes the index.
• With the Trash quick-folder selected, Cmd+D offers to empty the trash instead (with a confirmation showing the item count).

Clipboard History (`c"`)#

Access recently copied text items:

• Type c" to enter clipboard mode
• Browse recent text clips
• Press Enter to copy an item back to clipboard
• Press Delete to remove the selected entry from history

Note: History size is set by clipboard_history_limit (default 10, range 10-100; see Configuration); edit the config and reload (Cmd/Ctrl+Shift+;) to apply. On macOS the history is kept in memory and clears on restart; on Windows/Linux it is saved to disk and persists between launches. File/folder copies (both Cmd+C and Cmd+P) are excluded from the history.

Clipboard histories search example#

Recent Files & Folders (`rc"`)#

Type rc" to browse what you most recently opened and what recently landed on disk (downloads, screenshots), newest first. Add a term to filter: rc"report.

• Enter opens an entry, Cmd/Ctrl+F reveals it
• Cmd/Ctrl+D moves the entry's file to trash

Open a URL#

Type something that looks like a URL and Look offers to open it in your browser - no prefix needed.

• A structural URL (with a scheme, port, path, or localhost/IP - e.g. http://localhost:3000 or example.com/docs) shows an Open in browser row at the top of the results.
• A bare host.tld (e.g. github.com) shows the row after your local results, so it never displaces a real file or app match.
• URLs you open this way are remembered and resurface as Recently opened rows, ranked by frecency and filtered as you type.

Shared between the macOS and Windows/Linux apps.

Quick Folders#

Type a folder's name to pin it to the top of results (Enter opens it, Cmd+F reveals it) - even when it isn't part of the indexed file roots:

• Home folders - Desktop, Documents, Downloads, Pictures, Movies, Music.
• `Applications` - pins the /Applications folder (macOS). The indexer only walks Desktop/Documents/Downloads, so this is how you jump to /Applications; the apps inside it stay searchable as apps (a").
• `Trash` - pins the Trash; Cmd+D on it empties the Trash (see Move to Trash above).

Translation (`t"` / `tw"`)#

Quick translation without leaving the launcher:

• t"hello → Translate "hello" to Vietnamese/English/Japanese
• tw"word → Dictionary lookup with definitions and examples

Translate sentences, words via web#

Search words by MacOS's built-in LookUp#

Translation requires network connectivity.

Web Answers (optional)#

With web answers enabled (default), Look answers question-like queries inline:

• Knowledge lookups: a question or a multi-word entity that isn't indexed locally (e.g. sir alex ferguson) shows an answer card sourced from DuckDuckGo/Wikipedia, with clickable source labels.
• Instant converters: currency (100 usd to eur), weather, and crypto queries match their own narrow grammar and answer immediately.
• Web search suggestions: autocomplete rows appear below local results; Enter opens the suggestion in your browser.
• Layout: the answer card renders full-width when there are no local results, side-by-side with suggestions, or stacked above local results, depending on what the query returns.
• On macOS, Look can additionally fall back to the on-device Apple Intelligence model when local and web sources have no answer. Linux/Windows use web sources only.

Privacy notes:

• Prefix queries (a", f", d", r", c", rc", t", tw", :cmd) never trigger web lookups - they are launcher scopes, not questions.
• Turn the whole feature off in Settings → Advanced, or set ai_enabled=false in ~/.look.config to run fully offline.

Command Mode (`Cmd/Ctrl+/` or `:cmd` from home)#

Two ways in:

• Cmd/Ctrl+/ enters command mode and resumes the last command panel you visited (defaults to calc on first run); use Tab or Cmd+1..Cmd+6 to switch.
• From the home screen, type : followed by a known command id:
  • :calc 2+2 - the space after the command id is the live trigger; you switch with 2+2 already typed and can keep typing without pressing Enter.
  • :calc then Enter - switch with empty input.
  • The : shortcut only triggers when the word right after it is an exact known command id (calc, pomo, todo, kill, shell, sys); anything else (:foo, :Users/me/...) stays in normal search.
  • :kill chrome and :shell ... switch into command mode but never auto-execute - the existing kill confirmation and shell input gate still apply.

Built-in quick commands:

calc#

Supports ^, !, % (shorthand and modulo), constants pi/e, functions sqrt/abs/round/floor/ceil:

• 2^10 → 1024
• 4! → 24
• 200*15% → 30
• 10%3 → 1
• 2*pi → 6.2832

Most of these also work from the main input without entering command mode.

pomo#

A pomodoro focus timer that lives inside command mode.

• Editable session list - plan a sequence of focus + break blocks, each with its own duration and name (e.g. Deep Work 30m → Short Break 5m → Review 30m → Long Break 15m). The timer auto-advances through the list and loops the music folder while a session runs.
• Three timer styles (switchable via the gear icon): Modern Ring, Vintage Dial, Minimal Text.
• Background music: pick any folder of audio files (mp3, m4a, wav, aac, flac, ogg, aiff, alac). Tracks are streamed one at a time (no full-folder load), shuffled per launch, and looped at the end of the list.
• Standby fade - after 5s of no input the panel collapses to clock-only (the sidebar hides too); any key/mouse input restores it.
• "Ending soon" alert - at 10s remaining, a chime + a popover from the menu-bar timer (and a system notification, if granted) fires once per session.
• Menu-bar mini-timer - visible whenever a session is active, even when the launcher window is hidden. Click it to jump straight back into /pomo.
• Keyboard: Space start/pause • R reset • P toggle music play/pause.
• Persistence: the session list, selected timer style, and music folder path are saved to ~/.look.config and survive restarts.

todo#

A daily task tracker (:todo or Cmd/Ctrl+3).

• Day-grouped tasks - tasks live under their date; overdue days get a badge, and a done-today stat sits in the footer.
• Stats page - streak counter, 30-day trend chart, and a year heatmap of completed tasks.
• Keyboard: Ctrl+N adds a task, Ctrl+S saves, Enter/Escape confirm or cancel an edit. Double-click a task to edit it.
• Home-screen quick view - when today has tasks, the hint bar shows a clickable Todo done/total stat with an "Unfinished today" hover bubble.
• Shared storage - tasks persist in the local look.db and are shared between the macOS and Windows/Linux apps.

shell#

Run a shell command from the launcher. Input containing sudo shows an orange warning cue.

kill#

Force-kill a running app or process with explicit confirmation. Supports port-based targeting:

• kill :3000 - kills whatever owns port 3000
• kill port 3000 - same, verbose form
• Use Up/Down to navigate process results, Y/N to confirm or cancel

sys#

Displays system information at a glance.

Running Apps Switcher#

Available on macOS, Linux, and Windows. Modifier is Cmd on macOS and Alt on Linux/Windows.

When enabled, running-app icons fill the right half of the search bar (the search field takes the left half), right-aligned and growing leftward as more apps open. Each icon has a corner number badge; press Cmd/Alt+the badge digit on the home screen to activate that app. The launcher window stays the same size whether the row is shown or hidden.

• Stable order - icons sit in alphabetical order and don't shuffle when you switch apps. The badge digit for "Discord" stays the same until you launch or quit something.
• Ergonomic badge keys - easy-to-reach keys are assigned first. We pull from 1, 2, 3, 9, 8, 4, 7, 6, 5 in that order and sort the result ascending for display, so painful middle keys (5/6/7) only appear when you have many running apps:

• Windowless apps (macOS only - Finder with no Finder windows, App Store, etc.) get a fresh window via a Dock-style "reopen" instead of an empty flash. Hidden apps (Cmd+H) are unhidden first. On Linux/Windows the switcher only lists apps that currently own a visible window, so this case doesn't arise.
• Linux compositor support - focus dispatches via X11 _NET_ACTIVE_WINDOW (GNOME/KDE/i3), i3-msg (i3), swaymsg + wlr-foreign-toplevel (sway/wlroots), hyprctl (Hyprland), and a bundled GNOME Shell extension on GNOME Wayland.
• Show/hide via Settings → Appearance → Running Apps (on/off toggle).
• In command mode, the digit shortcuts keep their existing command-catalog semantics (calc / pomo / todo / kill / shell / sys); the running-apps switcher only fires on the home screen. Suspended modes (translate, command) also ignore the digit keys so the hidden strip can't fire from a stale cache.

Persisted as running_apps_placement in ~/.look.config - see Configuration.

Floating Layout (Inner Gap)#

Split the launcher into floating tiles, tiling-WM style, with the Inner Gap slider in Settings → Appearance (0-24 px, default 0):

• 0 keeps the classic single framed panel.
• Above 0, the search bar, results list, and preview panel become separate frosted tiles separated by transparent gaps, floating directly on the desktop.
• Each tile keeps the theme border, so the Border thickness/color settings apply per tile.
• With an empty query, only the search bar shows (resting state) - the columns appear as you type.
• A background image continues seamlessly across the tiles, as if the gaps were cut out of one picture.

Persisted as inner_gap in ~/.look.config and shared between the macOS and Windows/Linux apps.

On environments that can't composite the floating look faithfully (bare X11 WMs without a compositor, VMs with software rendering, blur-disabled stacks), Look keeps the classic framed panel with both columns visible and disables the Inner Gap slider. The saved value is untouched and applies again on a capable setup.

Background Image#

Add a custom background image:

1. Place image in ~/look_bg.png
2. Adjust opacity and blur in settings
3. Choose layout mode: fill, fit, tile, or stretch

Lazy Indexing#

When enabled (default), the app only reindexes when:

• File/app changes are detected
• Manual reload is triggered (Cmd/Ctrl+Shift+;)
• App restarts

Disable for immediate indexing on every launch (slower but fresher results).

Health Notifications#

Look surfaces setup problems instead of failing silently. A sticky banner appears when, for example, the global hotkey could not be registered or the GNOME Shell extension needs a re-login to load. Dismissing a notice is remembered, so the same issue won't nag on every launch. See Troubleshooting for the crash log location.

Settings Panel#

Open with Cmd/Ctrl+Shift+,. Contains three tabs:

Appearance#

• Theme: 7 built-in presets (Catppuccin, Tokyo Night, Rose Pine, Gruvbox, Dracula, Kanagawa, Custom)
• Tint Color: accent color (RGB + opacity)
• Blur: blur material and opacity
• Font: name and size
• Font Color: text color (RGB + opacity)
• Border: thickness and color
• Inner Gap: floating tile layout (0-24 px)
• Running Apps: show/hide the running-apps switcher

Advanced#

• Background image (path, layout mode, opacity, blur)
• Indexing settings (File Scan Depth: 1-12, File Scan Limit: 500-50000)
• AI / Web answers on/off
• Backend log level
• Launch at login
• Config reset: Create Fresh Config button with confirmation popup

Shortcuts#

• In-app keyboard shortcut documentation
• Toggle help screen with Cmd/Ctrl+H

Configuration#

Look uses a configuration file at ~/.look.config. Changes take effect immediately after saving, or you can press Cmd/Ctrl+Shift+; to reload.

Configuration File Location#

• Default: ~/.look.config
• Custom: Set LOOK_CONFIG_PATH environment variable
• Reload: Cmd/Ctrl+Shift+;
• Reset: Settings → Advanced → "Create Fresh Config"

Format#

• One key=value per line
• # starts a comment
• Unknown keys ignored
• Invalid values fall back to defaults

Backend Settings#

App Scanning#

app_scan_roots=/Applications,/System/Applications,/System/Applications/Utilities,/System/Library/CoreServices/Applications
app_scan_depth=3
app_exclude_paths=
app_exclude_names=

File Scanning#

file_scan_roots=Desktop,Documents,Downloads,Pictures,Videos
file_scan_extra_roots=
file_scan_depth=4
file_scan_limit=8000
file_exclude_paths=

Use file_scan_extra_roots to add user-specific directories on top of the defaults (overlap and risky-root validation is enforced).

Other Backend Options#

lazy_indexing_enabled=true
skip_dir_names=node_modules,target,build,dist,.git,vendor,out,coverage,tmp,cache,venv
backend_log_level=info
launch_at_login=false

Backend Keys Reference#

Web Answers#

ai_enabled=true

Gates all network answer features: the answer card (Wikipedia, DuckDuckGo), currency/weather/crypto converters, and web search suggestions. Set to false to run fully offline. On macOS the same key also gates the on-device Apple Intelligence fallback; there is no on-device model on Linux/Windows, but the key keeps the same name so both apps share config storage.

UI Theme Settings#

Theme Preset#

ui_theme=catppuccin

Available: catppuccin, tokyoNight, rosePine, gruvbox, dracula, kanagawa, custom

Appearance#

ui_tint_red=0.08
ui_tint_green=0.10
ui_tint_blue=0.12
ui_tint_opacity=0.55
ui_blur_material=hudWindow
ui_blur_opacity=0.95
ui_font_name=SF Pro Text
ui_font_size=14
ui_font_red=0.96
ui_font_green=0.96
ui_font_blue=0.98
ui_font_opacity=0.96
ui_border_thickness=1.0
ui_border_red=1.0
ui_border_green=1.0
ui_border_blue=1.0
ui_border_opacity=0.12

Floating Layout#

inner_gap=0

Home-screen inner gap in px (0-24). 0 keeps the classic framed panel; above 0 the home screen splits into floating tiles separated by this gap, each with its own theme border. Shared between the macOS and Windows/Linux apps.

Background Image#

ui_background_image=~/look_bg.png
ui_background_image_mode=fill
ui_background_image_opacity=0.5
ui_background_image_blur=10

Settings Panel#

settings_blur_multiplier=0.8

Running Apps Switcher#

running_apps_placement=right

When none, the running-apps row in the search bar is hidden and the Cmd/Alt+1..9 switching shortcut is disabled; any other value shows it. Legacy top/bottom values from older releases still load as "on" and normalize to right on next save. The key is auto-appended to existing ~/.look.config files on first Save Config, so upgrading from an older Look install doesn't reset other settings. See Features → Running Apps Switcher for the badge-key behavior.

Platform Workarounds (Linux)#

arch_disable_gpu=false
arch_disable_blur=false

Workarounds for WebKitGTK ghost rendering seen on Arch and similar stacks. arch_disable_gpu=true disables webview hardware acceleration (requires restart); arch_disable_blur=true drops the backdrop blur and forces an opaque tint. Both default off - flip them only if you see slider trails or overlapping popovers.

File-Only Settings (No Settings UI)#

These keys have no control in the Settings screens - edit ~/.look.config directly, then reload with Cmd/Ctrl+Shift+;, or restart Look. Out-of-range or unparseable values fall back to the listed default. More keys will be added here over time.

clipboard_history_limit=10

Ignored File Patterns#

Exclude noisy files from the index with gitignore-style path globs:

# ignored_patterns_<group>=Pattern1|Pattern2
ignored_patterns_browser=~/AppData/Local/BraveSoftware/**/*.log|~/AppData/Local/Google/Chrome/**/*.tmp
ignored_patterns_sqlite=~/Documents/git/project/**/*.db-wal|~/Documents/git/project/**/*.db-shm

Group patterns under any ignored_patterns_<group> key (the <group> label is free-form); all ignored_patterns_* entries are merged together.

• Glob syntax: *, **, ?, [abc]; separate patterns within a key with |
• macOS/Linux use / paths (~/Library/...); Windows uses native absolute paths. ~ expands to your home directory before matching
• Patterns match files only - they do not exclude folders from traversal

Search Aliases#

Define aliases to map search terms to related apps:

alias_note=Notion|Obsidian|Notes|Apple Notes|Bear|Logseq
alias_code=Visual Studio Code|VSCode|Cursor|Windsurf|IntelliJ IDEA|PyCharm|WebStorm|Neovim|Xcode|Zed
alias_term=Terminal|iTerm|iTerm2|Ghostty|WezTerm|Alacritty|Kitty|Warp
alias_chat=Slack|Discord|Telegram|Messages
alias_music=Spotify|Apple Music|Music
alias_brow=Safari|Arc|Google Chrome|Chrome|Firefox|Brave

Alias behavior:

• Aliases apply to app + System Settings search only
• Aliases boost matching apps but don't create synthetic results
• If an aliased app is not installed, no error is shown
• Keep lists short (5-10 targets) for best results

Troubleshooting#

Look Shows a Warning Banner#

Look surfaces setup problems in a sticky banner inside the launcher instead of failing silently. The two common ones:

• Global hotkey could not be registered - another app owns the shortcut. On GNOME Wayland, Look frees the default Alt+Space window-menu binding automatically; on other setups, rebind or close the conflicting app.
• GNOME extension needs a re-login (Linux) - the bundled GNOME Shell extension loads only after logging out and back in once after install.

Dismissing a banner is remembered, so the same issue won't reappear on every launch.

Hotkey Doesn't Open Launcher#

1. Check Spotlight shortcut conflict (macOS):
   • System Settings → Keyboard → Keyboard Shortcuts... → Spotlight
   • Disable or rebind "Show Spotlight search"
2. Relaunch Look and try again
3. Check if app is running:

ps aux | grep -i look

Results Seem Stale or Incomplete#

1. Reload configuration: Cmd/Ctrl+Shift+;
2. Check scan settings in ~/.look.config:
   • file_scan_roots
   • file_scan_depth (range: 1-12)
   • file_scan_limit (range: 500-50000)
3. Verify exclude rules aren't too broad
4. Keep lazy_indexing_enabled=true and use Cmd/Ctrl+Shift+; to force refresh

Translation Returns Warnings/No Result#

• Confirm network connectivity
• Check that translation service is accessible

No Answer Card for Questions#

• Web answers may be turned off - check Settings → Advanced, or ai_enabled in ~/.look.config
• Prefix queries (a", f", :cmd, ...) intentionally never trigger web lookups

App Doesn't Appear in Search#

1. Check app_scan_roots includes the app's location
2. Verify app_exclude_names doesn't exclude it
3. Reload config: Cmd/Ctrl+Shift+;

Launcher Opens Behind Another Window#

This is usually a focus-handoff timing issue. Hide the launcher (Escape) and reopen. If it reproduces consistently, please file an issue with your OS version.

Visual Glitches on Linux (slider trails, overlapping popovers)#

Some WebKitGTK + GPU stacks (seen on Arch) ghost-render. Two opt-in workarounds in ~/.look.config:

• arch_disable_gpu=true - disables webview hardware acceleration (requires restart)
• arch_disable_blur=true - drops backdrop blur, forces an opaque tint

High CPU or Slow First Launch#

The initial index scan is a one-time cost; subsequent launches use the cached SQLite index. If you have very large user directories, lower file_scan_depth and file_scan_limit in ~/.look.config.

A Config Change Was Ignored#

• Look reads ~/.look.config at launch; after editing manually, reload with Cmd/Ctrl+Shift+; or restart Look.
• Confirm you edited the active config path. LOOK_CONFIG_PATH overrides ~/.look.config when set.

App Crashed#

Crashes on Windows/Linux show a native dialog and append to a crash log:

• Linux: ~/.local/state/look/crash.log
• Windows: %LOCALAPPDATA%\look\crash.log

Please attach the last lines of that file when filing an issue.

First Launch Issues (macOS)#

Current releases are signed and notarized. If you still encounter Gatekeeper issues:

1. Confirm you installed a recent release
2. Check System Settings → Privacy & Security for any blocks
3. Legacy workaround (older builds only):
   • Right-click app → Open → confirm
   • Or use Privacy & Security → Open Anyway

Need to Inspect Local DB#

You can query the local SQLite database to inspect indexed candidates:

sqlite3 "$HOME/Library/Application Support/look/look.db" "SELECT id,title,use_count FROM candidates ORDER BY use_count DESC LIMIT 20;"

Reset Configuration#

To reset to default configuration:

1. Open Settings (Cmd/Ctrl+Shift+,)
2. Go to Advanced → "Create Fresh Config"
3. Confirm the action (press Y)

This replaces your current ~/.look.config with the latest default template.

Development#

Building from Source#

Requirements#

• macOS: macOS 15.0+, Xcode
• Windows/Linux: system deps (see BUILDING.md)
• All platforms: Rust stable toolchain (for the core engine)

Repository Structure#

look/
├── apps/macos/LauncherApp/    # SwiftUI shell (macOS)
├── apps/linows/               # Tauri v2 app (Windows + Linux)
│   └── src-tauri/             # Rust backend
├── core/                      # Rust workspace (shared)
│   ├── engine/                # Search & indexing
│   ├── matching/              # Fuzzy matching
│   ├── ranking/               # Result ranking
│   ├── storage/               # SQLite storage
│   ├── answers/               # Web answer sources (Wikipedia, currency, ...)
│   └── todo/                  # Shared todo backend
├── bridge/ffi/                # Swift-Rust FFI (macOS)
└── docs/                      # Documentation

Build Commands#

# Check Rust core workspace
cd core
cargo check --workspace

# Check FFI bridge (macOS)
cd bridge/ffi
cargo check

# Run macOS dev app
make app-run

# Run Tauri dev (Windows/Linux)
cd apps/linows
cargo tauri dev

Dev App Behavior#

make app-run:

• Builds local app bundle with Xcode (Debug)
• Stops any running Look process (including a Homebrew-installed instance)
• Launches with LOOK_CONFIG_PATH=$HOME/.look.dev.config
• Shows red TEST APP badge for visual distinction

Side-by-Side Dev Build#

make app-run-dev installs /Applications/Look Dev.app with a separate bundle id (noah-code.Look.Dev), so the Homebrew-installed Look.app stays untouched:

make app-run-dev

Override the dev config path when needed:

make app-run DEV_CONFIG_PATH="$HOME/.look.qa.config"
make app-run-dev DEV_CONFIG_PATH="$HOME/.look.qa.config"

Running Tests#

# Rust tests
cd core
cargo test --workspace

# FFI bridge tests
cd bridge/ffi
cargo test

Benchmarks#

Benchmarks live in a separate tools/perf crate (never bundled into a shipped binary):

cd tools/perf
cargo run --release --bin query_engine_bench     # query throughput + fuzzy scoring
cargo run --release --bin scoped_refresh_bench   # per-call refresh latency
cargo run --release --bin watcher_stress         # simulated event streams

Snapshots land under docs/bench-notes/ - add a new snapshot when scoring, matching, or indexing changes.

Architecture Overview#

Look uses a shared Rust core with platform-specific UI shells:

• macOS: SwiftUI shell communicating with Rust engine via FFI
• Windows + Linux: Tauri v2 shell (vanilla HTML/CSS/JS frontend) calling Rust engine directly as crate deps
• Rust Engine: Fast search and indexing, shared across all platforms
• SQLite Storage: Local database for candidates, usage data, and todo tasks

Core Components#

1. Search Engine: Handles fuzzy matching and ranking
2. Index Manager: Manages file/app indexing
3. Storage Layer: SQLite for persistence
4. Answers: Shared web answer sources (DuckDuckGo, Wikipedia, currency/weather/crypto)
5. FFI Bridge: Swift-Rust communication (macOS)
6. Tauri Commands: Direct Rust calls (Windows/Linux)

Contributing#

Contribution flow:

1. Branch from dev (not main)
2. Open PRs into dev - PRs to main are reserved for maintainer-coordinated hotfix/release work
3. Run local checks before opening a PR: bash cargo test --workspace --manifest-path core/Cargo.toml cargo test --manifest-path bridge/ffi/Cargo.toml
4. Update docs when user-visible behavior changes

See CONTRIBUTING.md and DEVELOPMENT.md for details.