Documentation

What is Lattice

Lattice is an AI-native macOS command center: a menu bar resident summoned by ⌥Space (rebindable) that launches apps, searches files, manages your clipboard, runs Shortcuts and drives AI tools from the keyboard. Native Swift 6 + SwiftUI + AppKit — no Electron, no accounts, no cloud sync.

It is four things at once: an evolved Spotlight, Everything for Mac, an assistant panel with an AI tool loop, and a home for app quick actions.

Up and running in 3 minutes

1. After installing, press ⌥Space (menu bar icon → Open Settings → General to rebind)
2. Type saf and press ↵ — Safari launches; type 12*(3+4) — the calculator pins 84 on top, ↵ copies it
3. Enter Search Files (type files, ↵), type any filename fragment, ↵ opens it
4. Copy some text, then enter Clipboard History (type clipboard); ⌘Y previews, ↵ pastes back
5. For AI: Open Settings → AI, save an API key and enable AI Requests, then use Ask AI in the palette

Hotkey reference

Four modes

• Commands: apps, system commands, Quicklinks, Shortcuts, agents, calculator — one ranking (exact > prefix > substring > keyword, with bounded usage weighting)
• Search Files: full-disk filename search with directory scoping (Choose Folder)
• Clipboard History: text and URL history — search, preview, paste back
• Ask AI: AI conversation with a tool loop; Esc cancels

Query syntax

File search combines lexical operators; quoted phrases match verbatim:

# term + extension filter
report ext:pdf

# path constraint + kind + sort
path:Downloads kind:file sort:size

# quoted phrase + multiple extensions
"meeting notes" ext:md,tex

# folders only
kind:folder config

How the index works

• Self-built SQLite index covering your Home, /Applications, /System/Applications and /Library by default; add, remove or rebuild roots in Settings → File Index
• FTS5 trigram index serves ≥3-character substring queries; 1–2 characters use the prefix index
• FSEvents live updates sync changes within 2s; restarts resume from the event cursor without rescanning
• ~/Library/CloudStorage and iCloud directories are deliberately excluded to avoid FileProvider placeholder stalls
• Directories without Full Disk Access are silently skipped (with guidance in Settings)

Per-app actions & argument mode

Select an app and press ⌘K to expand its dedicated actions; press ⇥ to enter Arguments mode and type launch flags directly (quotes wrap values with spaces). Each app remembers its recently used arguments — an empty query lists them for reuse.

Arguments pass through NSWorkspace's argv — no shell involved, no extra system permission prompts.

Running macOS Shortcuts

Type a Shortcut's name in Commands to find and run it. Execution goes through the fixed /usr/bin/shortcuts CLI (argv-only, no shell). AI can query and run them via the shortcuts.list / shortcuts.run tools, with confirmation before each run.

Clipboard history

• 650ms changeCount polling with deduplication; 500 entries by default, configurable 1–10,000, 1MB per entry
• ⌘Y rich preview, ↵ to paste back, clearing requires confirmation
• Concealed / Transient / AutoGenerated types are ignored by default (password managers etc.); unmarked sensitive text is still recorded — disable in Settings if concerned

Quicklinks & calculator

Add Quicklinks in Settings: http/https/file URLs with {query} placeholders, instantly available in the palette. The calculator needs no mode at all — type an expression in Commands and the answer appears; ↵ copies it.

Agents & Skills

Create agents in Settings → Agents: name them, pick a tool whitelist, and invoke by name from the palette. Skills definitions are scanned from ~/.config/lattice/skills and similar directories; an example ships in Examples/Skills.

Ask AI & tool approval

AI is off by default. Save an OpenAI-compatible API key in Settings → AI (Keychain only) and enable AI Requests to unlock Ask AI. The model runs up to 8 tool rounds, at most 8 calls per round, 256KB per tool output.

Configuring MCP servers

Add stdio server configs in Settings → MCP. Connecting shows the program and arguments for confirmation:

{ "name": "Lattice local fixture",
  "transport": "stdio",
  "command": "/usr/bin/python3",
  "args": ["/Users/you/LatticeMCPFixture.py"],
  "env": {} }

Credentials are stored in Keychain and referenced via secretEnvironment — never persisted into the JSON config. Third-party server processes run with your user permissions; tool approval is not an OS sandbox. Only connect servers you trust.

Privacy & data

• All local data lives in ~/Library/Application Support/Lattice/lattice.sqlite (0700 directory, plaintext content)
• API keys and MCP credentials are Keychain-only (WhenUnlockedThisDeviceOnly)
• Zero network requests while AI is off; when on, requests go only to your configured provider
• Logs never record prompts, clipboard contents, credentials or server stderr
• The global hotkey uses Carbon RegisterEventHotKey — no global key listening, no Accessibility permission needed (except the Lock Screen event)

FAQ

• Why is there no Dock icon? — Lattice is a menu bar app (LSUIElement); it lives in the menu bar only.
• How long is the first index? — Depends on file count; ~14 minutes for 5.5M files here. FSEvents maintains it afterwards.
• Does it conflict with Spotlight? — Completely independent: Lattice builds its own index and never reads or touches Spotlight.
• Intel Macs? — The current bundle is arm64; the source archive builds anywhere, but Intel hardware is untested.
• How do I uninstall? — Disable Launch at Login, delete API keys, quit and remove the app; the data directory and Keychain items remain until you remove them.