Menu Bar App

The lattices menu bar app sits in your menu bar and controls your workspace from there.

Installation

lats app              # Build (or download) and launch
lats app install      # Register launch-at-login and launch now
lats app update       # Swap in the latest app release only
lats app build        # Rebuild from source
lats app restart      # Quit, rebuild, relaunch
lats app quit         # Stop the app

The first run builds from source if Swift is available, otherwise downloads a pre-built binary from GitHub releases.

Use lats app install when you want the companion to start now and open automatically at login. It installs a user LaunchAgent in ~/Library/LaunchAgents; inspect it with lats app login status and remove it with lats app login disable.

Updating

lats update           # Update the CLI and app together

lats update reinstalls @lattices/lattices with the package manager that owns your global install (npm, bun, or pnpm). It re-registers launch-at-login so the LaunchAgent points at the new install, and it relaunches the app if it was running. Pass --force to reinstall when you already have the latest version.

Command palette

Press Control+Option+Space from anywhere to open the command palette. It's a searchable list of every action the app can perform, with fuzzy matching on titles and subtitles.

Project commands

Window commands

Available for running sessions:

Tab group commands

Available when groups are configured in ~/.lattices/workspace.json (see Tab Groups):

Layer commands

Available when layers are configured in ~/.lattices/workspace.json (see Layers):

App commands

Overlay actors and HUDs

Persistent overlay actors can be hidden or restored with Hyper+B. Apps can publish a static hover dashboard by exposing:

.lattices/hud/manifest.json

Register and publish one:

lats hud register .lattices/hud/manifest.json --publish

The manifest points to a local index.html, optional icon, app activation target, HUD dimensions, and optional app-owned sources metadata for logs or state files. Lattices hosts the actor and loads the dashboard through a transparent WKWebView; the app owns the renderer and writes its own logs in the places it already uses.

Project discovery

The app scans a configurable root directory (up to 3 levels deep) for .lattices.json files. It skips .git/ and node_modules/.

Auto-detection for the scan root checks these paths in order: ~/dev, ~/Developer, ~/projects, ~/src.

For each project found, the app reads:

• Pane names and commands from .lattices.json
• Dev command and package manager from package.json
• Running status by checking tmux has-session

Session management

The app calls the lattices CLI for session operations. Launch runs lats start in the project directory, Sync runs lats sync to reconcile panes, and Restart runs lats restart <pane> to kill and re-run a pane's process. Detach and Kill call tmux detach-client and tmux kill-session directly.

Window tiling

The app can tile terminal windows to preset screen positions via the command palette. It finds windows by their [lattices:session-name] title tag.

For Terminal.app and iTerm2, tiling uses AppleScript to set window bounds by matching the title tag. For other terminals, it tiles the frontmost window.

Tile positions (app)

Moving windows between displays and desktops

In Overview, select a window and open Move in the floating controls. Each destination includes the display name and desktop number, such as DELL S3422DWG · Desktop 2 or Action Agent Layer · Desktop 2. Bring Here selects the current desktop on the display that contains the Overview window.

Drag a window shape onto another display map to move it to that display's current desktop. Drop it onto a desktop thumbnail to choose that exact desktop. The destination highlight identifies the drop target. Selecting a window shows its controls over the canvas; the display maps and arrangement tray keep their positions.

Desktop Inventory and Studio also offer window movement in their context menus:

• Bring Here moves the selection to the UI's display and current desktop.
• Move to Desktop lists each display and its desktops.
• Move to Next Monitor cycles through displays and preserves normalized window position and size.
• Move to Monitor selects a display's current desktop.
• Move & Place selects a display and a placement slot for one window.

A right-click on a member of a multi-selection targets the whole selection. Each window keeps its own normalized frame. Move & Place is available for a single window. Desktop destinations remain available with one display.

The UI, CLI, and daemon use the same verified movement operation. If a window is on an inactive desktop, Lattices first carries it onto its source display's current desktop. It then transfers the window to the chosen display and desktop. Mission Control can appear during the move. Keep the pointer free until the operation finishes.

A move succeeds only after Lattices verifies the final display, desktop, and frame. If a step fails, Lattices attempts to restore the original location and reports the failure. The interface keeps the selection and refreshes the observed window state.

Space navigation

"Go to" commands can switch macOS Spaces to reach a window on a different desktop. The app uses a three-path fallback:

1. CGWindowList (needs Screen Recording) — looks up the window by title tag, finds its Space via SkyLight, switches to it, then raises the window
2. Accessibility API (needs Accessibility) — finds the window via AXUIElement, raises it, and activates the app
3. AppleScript — iterates windows by name for Terminal/iTerm2, or bare-activates for other terminals

When a window is found and focused, the app flashes a green border highlight around it for ~1 second so you can spot it immediately.

Grant Screen Recording and Accessibility permissions in System Settings > Privacy & Security for all three paths to work.

Instant space switching

With Accessibility permission, the app intercepts Ctrl+← / Ctrl+→ before Mission Control and switches Spaces through a synthetic Dock swipe under a screen-update freeze — the real switch path, so Dock's space model, Mission Control, and space-change observers all stay consistent, while the freeze makes it render as an instant cut. A desktop filmstrip appears mid-screen over a subtle neutral dimmed backdrop. The focus frame stays centered while window-layout previews slide through it; the small rail below represents every desktop. The preview reads the existing desktop inventory without taking screenshots or scanning windows on each keypress. Pressing past the first or last desktop is silent. Reduce Motion updates the selection without sliding; Reduce Transparency makes the tray and canvas backdrop opaque.

While the filmstrip is visible, Control+Up, Control+Down, or Control+minus opens the full connected desktop canvas in one motion. You can also open it directly under the pointer: hold the right mouse button and pull upward, or hold Control+Option and scroll down. An ordinary right-click still opens its context menu. The opening scroll's remaining movement and momentum are consumed so they cannot immediately change the new canvas camera.

The canvas stays open when you release the button or modifiers. Moving the pointer highlights a desktop without moving the canvas; Left/Right or a single click also chooses it. Up (with or without Control) and plus zoom toward the highlighted desktop. Down and minus zoom back out. Enter or a double-click lands there; Escape cancels without switching. Zooming never lands. Control+Option+scroll zooms around the pointer, ordinary scrolling pans, and the bottom-left minimap repositions the view. Pinch, Command+scroll, and the zoom buttons also work. Fit shows all desktops. Text fields keep their arrow keys. The Control+Option tiling HUD and Spatial Lens stay inactive while this navigator owns the gesture.

Every page in the main window has a Zoom out control in its header. It opens the same connected desktop canvas over the current page. Back to… returns to that page with its draft, filters, and local view state intact. Choosing a sidebar page leaves the canvas and navigates normally.

Agents can move the tray via settings.spaceBezel.set (top, bottom, center, or travelEdge to dock at the edge of travel). Desktop shimmer in Settings > Keyboard adjusts the passing light from Off to its original strength, with a subtle 15% default. Rapid switches share one pass instead of stacking light. Changes apply on the next switch without restarting; Reduce Motion and Reduce Transparency suppress the effect. Agents can also set it with settings.spaceBezel.set {"shimmerIntensity":0.15} (range 0–1; zero is off). The filmstrip stays visible while the switch is in progress, then waits 0.85 seconds after landing before its 0.12-second fade. Only bare Ctrl+arrows are claimed by Instant Space Switching; Ctrl+Option+arrows tile, and Ctrl+Option+Shift+arrows browse layers. While the feature is on, the app disables Mission Control's "Move left/right a space" symbolic hotkeys (they would replay the slide animation); the original setting is restored when the feature is toggled off or the app quits. Toggle it in Settings > Keyboard > "Instant Space Switching".

Voice commands

See Voice Commands for the full guide.

Press Hyper+D to open the voice command window. Hold Option to speak, release to stop. Lattices transcribes via Vox, matches to an intent, and executes. Built-in commands: find, show, open, tile, kill, scan.

The provider-backed assistant can run in parallel, offering follow-up suggestions in the AI corner. Configure the provider and credentials in Settings > Voice. Workspace chat itself uses Scout and needs no separate key.

Settings

Open via the command palette or the gear icon in the main view. The settings window has five tabs:

General

Mode controls how the app handles session interaction:

• Learning — shows tmux keybinding hints when you detach (helpful while getting used to tmux)
• Auto — detaches sessions automatically (fewer prompts)

Keyboard Remaps

Keyboard remaps are enabled by default for the laptop-friendly rule:

• hold Caps Lock -> Hyper (Control + Option + Shift + Command)
• tap Caps Lock -> Escape

Holding Control + Option is quiet by default. Control+Option+arrows tile the current window; add Shift to browse layers. Existing custom bindings remain available in Settings > Shortcuts.

The pointer picker is optional under Settings > Shortcuts > Ctrl+Option hold. With Spatial Lens enabled, holding physical Control + Option reveals eight contextual placement targets around the pointer. Choose a side to preview left, right, top, or bottom placement, or choose a corner for quarter placement. A deliberate outer flick well beyond a side target previews the physically adjacent display in that direction; release either modifier to commit the one visible proposal. Pull back before release to return to the original display; release in the neutral center or press another key to cancel.

Repeated placement follows the window's live geometry: half, third, two-thirds, then half again. The exact Control + Option hold deliberately excludes Command and Shift, so Caps Lock continues to own the Hyper layer.

Rules live in ~/.lattices/keyboard-remaps.json, and the Settings toggle can turn the layer off. Keyboard remaps require Accessibility permission because they use a local event tap.

Companion

Shows the secure local bridge status, Mac bridge fingerprint, supported capability grants, and paired iPad or iPhone devices. The paired-device list shows each device fingerprint, last-seen time, and granted capabilities. You can refresh the list, revoke an individual device, or forget all trusted companions.

The local companion bridge and trackpad proxy are off by default for privacy. Turn the bridge on in Settings > Companion, or open lattices://companion/enable to enable the bridge and jump straight to Companion settings. lattices://companion/disable turns it off again.

The trackpad proxy toggle lives here. Paired devices still need the input.trackpad grant before they can send pointer events.

AI

Shows assistant readiness and the selected provider's authentication state.

Shortcuts

Shows keyboard shortcut reference. These are the defaults; change them from Settings > Shortcuts. Hyper means Control+Option+Shift+Command. With keyboard remaps on, holding Caps Lock is Hyper.

Tiling and placement:

Control+Option pointer controls are off by default. Choose Tile HUD or Spatial Lens in Settings to enable one of those placement modes.

Spaces and layers:

Windows and panels:

Voice Command and Search have no default binding. Assign one in Settings > Shortcuts.

Inside tmux:

Hyper+L opens Studio on its Overview page; close it with Escape or q when the map owns keyboard focus, or use the window close button. Hyper+3 opens or dismisses the HUD and its miniature workspace map. The Scattered and Full HUD presets intentionally retain a faint, non-interactive ambient surface after dismissal. Neither UI is the read-only terminal lats map command; see that page for exact side effects, full-teardown steps, and tab-stack cleanup.

Studio's Layers panel lists the Cmd+Option layers in pad order. Picking one scopes the canvas to the layer's windows that are showing, and the inspector lists each of its entries with the windows it matched and where each one is: on another desktop or display, parked, hidden, or nothing, when no window matches. Picking a layer only looks; the inspector's Cmd+Option key switches to it.

In-place window tools

Press Hyper+G to arrange the real windows on the current desktop without switching to a thumbnail survey. Hover a real app window to reveal its dashed click to select outline, then click it to add or remove it from the selection. Selected windows have solid green numbered outlines; the last one selected is the active target for single-window actions. You can also select from the Windows drawer in the header or use letter hints. The bottom shelf shows the three-step flow—Select, Arrange, Finish—and groups actions by timing:

• Fill expands the active selected window into open space immediately.
• Grid moves two or more selected windows into a balanced grid immediately.
• Swap exchanges the first two selected windows.
• Place stages an exact grid position for the active selected window; it applies only when you Keep changes.
• More exposes tab groups, layers, quick placements, and Hyperspace.

Grid, Fill, and Swap update the live desktop while Hyper+G remains open. Press Keep changes or Return to accept those live moves and apply staged changes. Press Restore or Escape to discard staged changes and restore the window frames and stacking order from when Hyper+G opened. Inline Now and Keep labels distinguish immediate actions from staged actions before anything moves.

Snapshot starts a three-second countdown, captures the complete display without closing or changing Hyper+G, copies the PNG to the clipboard, and saves the same image as a Runs artifact. The command-line equivalent is lats capture display [index] --clipboard --delay 3.

Agent screenshots

When a screenshot is requested through the daemon socket (lattices capture window|display, or any capture.screenshot* call), Lattices draws a coral hairline around what was captured for about a second. A tag names the agent, where it called from (this Mac, or ssh <ip>) and its project. The cue appears after the shot and is excluded from screen capture, so it never shows up in an image. Screenshots Lattices takes for itself don't trigger it.

Each one is also appended to ~/.lattices/audit/captures.jsonl with the caller, target and artifact path. Read it with lattices capture log [--limit N] [--json]. The CLI detects Claude Code, Codex, opencode and Cursor from their environment. Set LATTICES_AGENT to name any other agent.

Docs

Embedded quick reference with glossary, "how it works" steps, and links to open the full config.md and concepts.md docs.

Supported terminals

"yes" means full AppleScript-based window matching by title tag. "activate" means the app is brought to front but a specific window can't be targeted. "frontmost" means tiling applies to whatever window is in front.

Screen OCR

See Screen OCR for full details on configuration, scanning, search, and agent usage.

The app reads text from visible windows using Apple's Vision framework and stores results in a local SQLite database with FTS5 full-text search. Agents can use this to "see" what's on screen.

How it works

1. Every 60 seconds, the app captures the top visible windows as images
2. A SHA256 hash detects whether the window content has changed
3. Changed windows are processed through VNRecognizeTextRequest (fast mode)
4. Results are stored in ~/.lattices/ocr.db with full-text indexing
5. Entries older than 3 days are automatically purged

Desktop Inventory integration

Desktop Inventory and omni search use OCR to find windows by their content — not just by title or app name. Matching windows can include contextual text snippets. Hyper+G's optional drawer is a compact roster for the current display; use Desktop Inventory or omni search when the on-screen text is the target.

API access

Agents can query OCR data through four API methods:

import { daemonCall } from '@lattices/lattices'

// Find windows showing error messages
const errors = await daemonCall('ocr.search', { query: 'error OR failed' })

// Read what's currently on screen
const snapshot = await daemonCall('ocr.snapshot')

More in the Agent API reference.

Requirements

• Screen Recording permission — required to capture window and display images
• Granted via System Settings > Privacy & Security > Screen Recording

Local services

The menu bar process hosts its services on private Unix sockets in ~/.lattices/run (see LatticesLocalEndpoints). LATTICES_RUNTIME_DIR moves that directory for isolated tests.

The sockets open when the app launches and close when it quits. Voice does not require an external voxd for normal operation.

Each WebSocket service requires its token in the x-lattices-token header during the upgrade. lats, daemonCall() and the MCP server read the token for you. Loopback TCP (9399 for the daemon, 9398 for voice, 9397 for speech) is a compatibility switch, off by default; see Private IPC and the gateway.

Agent API server

The menu bar app serves the agent API on lattices.sock. It starts when the app launches and stops when the app quits.

Checking status

lats daemon status

Or programmatically:

import { isDaemonRunning, daemonCall } from '@lattices/lattices'

if (await isDaemonRunning()) {
  const status = await daemonCall('daemon.status')
  console.log(status) // { uptime, clientCount, version, windowCount, tmuxSessionCount }
}

What it provides

• RPC methods for reading windows, sessions, projects, spaces, layers, processes, terminals, and OCR. Also launching/killing sessions, tiling windows, switching layers, and managing tab groups.
• 5 real-time events (windows.changed, tmux.changed, processes.changed, layer.switched, ocr.scanComplete) broadcast to all connected clients.
• Window tracking that monitors the desktop window list and correlates windows to lats sessions via title tags.
• Space awareness, so it knows which macOS Space each window is on.

Security

The socket directory is mode 0700 and the socket and token are mode 0600, so only your user account can connect. The daemon also checks the connected peer's user id. Any program running as your user can read the token; this is an account boundary, not isolation between programs. The daemon is not reachable from the network. Remote access goes through the separate gateway (lats gateway start --tailnet) and its approved method grants.

Full method list in the Agent API reference.

Diagnostics

The diagnostics panel shows a timestamped log of window navigation attempts, including which path succeeded or failed. Useful for debugging Screen Recording / Accessibility permission issues.