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.

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
• Customizable themes: Multiple built-in themes with full customization options
• 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" 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
• 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, force quit, shell commands, and system info
• Customizable Themes: Multiple built-in themes including Catppuccin, Tokyo Night, and more
• Privacy-First: No account, no telemetry, network only on explicit 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 (Alt+Space) is configurable in Settings → Appearance.

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

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:

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 and kill#

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

• 2^10 → 1024
• 4! → 24
• 200*15% → 30 (percent shorthand)
• sqrt(2) → 1.4142
• 2*pi → 6.2832
• 10%3 → 1 (modulo between operands)

Kill a process by port — open command mode with Cmd+/ (macOS) or Ctrl+/ (Windows/Linux), then:

• kill :3000 — kills whatever owns port 3000 (with confirmation)
• kill port 3000 — same thing, verbose form

Query Aliases#

Define aliases in ~/.look.config 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

• Aliases apply to app + System Settings search only
• Aliases boost matching apps but don't create synthetic results
• Keep lists short (5-10 targets) for best results

Typical Workflow#

1. Press Cmd+Space (macOS) or Alt+Space (Windows/Linux) to open launcher
2. Type to search apps/files/folders/settings
3. Use Tab/Shift+Tab or arrow keys to navigate
4. Press Enter to open

Keyboard Shortcuts#

Global Shortcuts#

Navigation#

Actions#

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

Command Mode#

Cmd+1..Cmd+5 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#

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 and paste 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.
• 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.

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

Note: Clipboard history is in-memory only and cleared on restart. File/folder copies (both Cmd+C and Cmd+P) are excluded from the history.

Clipboard histories search example#

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.

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

Two ways in:

• Cmd+/ enters command mode and resumes the last command panel you visited (defaults to calc on first run); use Tab or Cmd+1–5 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, 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.

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

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.

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

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+Shift+;)
• App restarts

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

Settings Panel#

Open with Cmd+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

Advanced#

• Background image (path, layout mode, opacity, blur)
• Indexing settings (File Scan Depth: 1-12, File Scan Limit: 500-50000)
• 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+H

Configuration#

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

Configuration File Location#

• Default: ~/.look.config
• Custom: Set LOOK_CONFIG_PATH environment variable
• Reload: Cmd+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
file_scan_extra_roots=
file_scan_depth=4
file_scan_limit=4000
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,library,applications
backend_log_level=info
launch_at_login=false

Backend Keys Reference#

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

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 (macOS only)#

running_apps_placement=right

When none, the running-apps row in the search bar is hidden and the Cmd+1..Cmd+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.

Linux and Windows configs currently ignore this key — the strip lives only in the macOS shell at this time.

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#

Hotkey Doesn't Open Launcher#

1. Check Spotlight shortcut conflict:
   • 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 Look

Results Seem Stale or Incomplete#

1. Reload configuration: Cmd+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+Shift+; to force refresh

Translation Returns Warnings/No Result#

• Confirm network connectivity
• Check that translation service is accessible

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+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 macOS version.

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+Shift+; or restart Look.
• Confirm you edited the active config path. LOOK_CONFIG_PATH overrides ~/.look.config when set.

First Launch Issues#

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+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: Rust stable toolchain, system deps (see BUILDING.md)
• Rust stable toolchain (for core engine)

Repository Structure#

look/
├── apps/macos/LauncherApp/    # SwiftUI shell (macOS)
├── apps/linows/               # Tauri v2 app (Windows + Linux)
│   └── src-tauri/             # Rust backend
├── core/                       # Rust engine (shared)
│   ├── engine/                # Search & indexing
│   ├── matching/              # Fuzzy matching
│   ├── ranking/               # Result ranking
│   └── storage/               # SQLite storage
├── 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#

Run the query-engine benchmark:

cargo run --manifest-path core/engine/Cargo.toml --example perf_bench

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 and usage data

Core Components#

1. Search Engine: Handles fuzzy matching and ranking
2. Index Manager: Manages file/app indexing
3. Storage Layer: SQLite for persistence
4. FFI Bridge: Swift-Rust communication (macOS)
5. 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.