Luma

Smart launcher for you, and your AI agent

A Linux launcher that finds apps, files — and photos by what's in them. The same index is open to AI agents: ask one for "the photo of a bear" and it finds it in seconds.

For humans

For AI agents

_{Same prompt, one run each (Claude Code, Sonnet 5.5, medium effort): 11 s with Luma, 1 min 26 s without. Both at 3x speed. More on agents.}

Install

curl -fsSL https://raw.githubusercontent.com/sakurartro/luma/main/install.sh | sh

The script downloads the binary into ~/.local/bin (or a path of your choice: ... | sh -s /usr/local/bin). To update later: luma update (installs the latest release next to the current binary if it is newer).

Setup

bind = SUPER, Space, exec, luma --toggle

hl.bind("SUPER + SPACE", hl.dsp.exec_cmd("luma --toggle"))

windowrule = float, class:^(luma-rust)$

o.window("^(luma-rust)$", { float = true, center = true })

binds {
    Mod+Space { spawn "luma" "--toggle"; }
}

window-rule {
    match app-id="luma-rust"
    open-floating true
}

Features

Search

• Fuzzy search of applications and files
• Semantic photo search (CLIP) — opt-in; matching files show a S(N%) match-strength badge
• Text-in-image search (OCR) — opt-in; matching files show a T(N%) badge
• Full-text search inside documents (txt, md, pdf, docx…) — opt-in; matches show a snippet of the text
• Calculator (2 + 2) and currency conversion (100 usd to eur)

Apps

• Applications from all XDG dirs — system, ~/.local/share, Flatpak, Snap; a user .desktop override shadows the system entry
• Launch ranking from usage stats (with time decay), pinned apps on top (right-click to pin/unpin)
• Category filter pills

Files and photos

• Separate views for apps, files, photos and settings (Alt+1…Alt+4)
• File type icons and cached photo thumbnails in the files grid
• File index with a background watcher and scan progress

System

• Power menu — shutdown, reboot, suspend, lock (power button in the bottom bar)
• Settings menu in the launcher (Alt+4 / Ctrl+,) — edits settings.json for you
• Full name on hover when a label is truncated

For AI agents

• MCP server (luma mcp) and CLI (luma query) over the same photo and screenshot index — see below
• One-click connect for Claude Code, Codex and opencode in Settings → Agents

Local by default — the index and the models stay on your machine; see Privacy.

For AI agents

An agent that is asked to find a photo usually walks the disk with find and opens files one by one. Luma already holds a CLIP and OCR index of your photos, so the agent asks it instead: one call, under a second, by what is in the picture or by the words written on it.

Connect — Settings → Agents (Alt+4) has a button for Claude Code, Codex and opencode: it registers luma mcp with the agent and switches the agent API on. By hand:

claude mcp add luma --scope user -- luma mcp
codex mcp add luma -- luma mcp

and set "agent_api": true in ~/.config/luma/settings.json (no restart needed). The API is off by default.

The server offers two tools: luma_search_images (what the picture shows, English queries) and luma_search_text (words written on it, English text). Each returns the best matches with a 0–100 score.

Requirements — Luma must be running, and semantic (for images) and/or ocr (for text) must be on, with indexing done. Only folders in search_dirs are searched. With a search not ready the tool answers with a message saying what to enable.

Without MCP — luma query clip "river in fog" and luma query ocr "connection refused" print one JSON line. agent/skills/luma/SKILL.md is a skill that teaches an agent to use them.

Privacy

Nothing leaves your machine except two things you can turn off: the model download (semantic / ocr, once) and exchange rates for 100 usd to eur (currency, cached for an hour). Photos, thumbnails, the index and agent queries stay local.

Usage

Configuration

Edit settings in the launcher (Alt+4 / Ctrl+,) or by hand in ~/.config/luma/settings.json. Hand edits, search_dirs, exclude_dirs, semantic and ocr apply after a restart (the menu offers a Restart button); everything else applies at once. New options are appended with their defaults; a broken file falls back to defaults and is kept.

semantic and ocr cost nothing while off; turning them off keeps the models and index on disk for later.

Where things live ($XDG_CONFIG_HOME / $XDG_CACHE_HOME respected): ~/.config/luma/ — settings, main.sqlite3, models/; ~/.cache/luma/thumbs — photo thumbnails. Apps are read from applications/ in $XDG_DATA_HOME and every $XDG_DATA_DIRS entry, refreshed when those dirs change.

Full example (the defaults):

{
  "bg": "#0E120B", "surface": "#151B10", "hover": "#1E2716", "selected": "#28331C",
  "border": "#2C3620", "accent": "#A9B665", "text": "#E4E7D0", "text_dim": "#7E8A6C",
  "search_dirs": ["~/Documents", "~/Pictures", "~/Desktop"],
  "hide_patterns": ["."],
  "exclude_dirs": [],
  "semantic": false,
  "ocr": false,
  "docs": false,
  "agent_api": false,
  "currency": true
}

Palettes

{"bg": "#0D1117", "surface": "#161B22", "hover": "#1C2431", "selected": "#24304A", "border": "#2D3748", "accent": "#58A6FF", "text": "#E6EDF3", "text_dim": "#8B949E"}

{"bg": "#282828", "surface": "#32302F", "hover": "#3C3836", "selected": "#504945", "border": "#665C54", "accent": "#D8A657", "text": "#FBF1C7", "text_dim": "#A89984"}

{"bg": "#FBF7EF", "surface": "#F1EBDD", "hover": "#E9E1CE", "selected": "#DFE4CB", "border": "#D3CBB2", "accent": "#5B7A3A", "text": "#2E3324", "text_dim": "#8A8B76"}

Requirements

• Linux (glibc 2.39+ — Ubuntu 24.04, Fedora 40+, Arch; the ONNX runtime of the semantic search sets this floor)
• The prebuilt binary links at runtime against libfontconfig, libGL (mesa) and libxkbcommon
• Power menu uses systemd: systemctl poweroff|reboot|suspend; lock is loginctl lock-session, so a locker must listen for it (e.g. hypridle with lock_cmd)

Build from source

cargo build --release

Dev packages (Debian/Ubuntu naming): libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libxcb1-dev. Binary: target/release/luma.

Troubleshooting

• Reset — delete ~/.config/luma/ (settings and database are recreated; models are downloaded again if enabled)
• Wrong or stale thumbnails — delete ~/.cache/luma/thumbs (regenerated on demand)
• Stuck hotkey — kill the process or remove $XDG_RUNTIME_DIR/luma-rust.sock (or /tmp/luma-rust-<uid>.sock)
• Agent does not see Luma — Luma must be running; claude mcp list should show luma; with semantic / ocr off the tools return a hint, not results
• Logs go to stderr — run Luma from a terminal to see them

Update

luma update

Uninstall

rm -f ~/.local/bin/luma ~/.local/bin/luma_rust && rm -rf ~/.config/luma ~/.cache/luma

luma_rust is the old binary name; installs from before the rename keep it as a link. If you connected an agent, remove it there too: Settings → Agents, or claude mcp remove luma.

License

GPL-3.0