Lattices — Assistant Knowledge

You are reading the Workspace Assistant's knowledge base. It summarizes what Lattices can do and links to the deeper docs. Treat the structured context in your prompt (current settings, file paths, CLI commands) as ground truth for this user's configuration; treat this file as ground truth for how Lattices works. When a question goes deeper than this summary, name the relevant doc (see References) instead of guessing.

What Lattices is

Lattices is an agentic window manager for macOS — a programmable workspace that pairs a native menu bar app with managed tmux sessions and a scriptable agent API. Three layers, one product:

1. Programmable workspace — a CLI and a WebSocket agent API (ws://127.0.0.1:9399, 35+ methods, real-time events) that let scripts and AI agents observe and drive the desktop the same way a person does.
2. Smart layout manager — the menu bar app tracks every window across all monitors: tiling, switchable layers, snap zones, and screen-text indexing.
3. Managed tmux sessions — declare a dev environment in .lattices.json; Lattices builds it, runs it, and keeps it alive across reboots.

Requirements: macOS 26+, Node 18+; tmux only for session management. See Overview and Concepts.

Capability map

Each area below is a one-paragraph summary plus the doc to cite for detail.

Window tiling & placement

Snap windows to preset positions — halves, quarters, thirds, maximize, center — from the command palette or lattices tile <position>. There is also a grid placement primitive: compact CxR:c,r starts at 1 for command entry, while canonical grid:CxR:c,r starts at 0 for APIs. → Tiling reference, positions in Configuration.

Workspace layers & tab groups

Group projects into named layers you can switch between, and tab-group related windows. workspace.json layers launch/focus/tile projects. Studio layers are rule-backed live window sets persisted in ~/.lattices/layers.json; their clauses support app/title/session exact, substring, regex, Space, visibility, and exclusion matches. For an ephemeral cross-app stack, select windows in Hyperspace and press Cmd+T or say “stack these as tabs” / “add these up”; use the HUD grid button to fan them out. Agents call tabStacks.create, tabStacks.add, tabStacks.select, and tabStacks.layout. → Layers.

Command palette & menu bar app

The palette (Cmd+Shift+M) is the app's primary surface: launch projects, tile, sync, restart, open settings — all searchable. → Menu Bar App.

tmux sessions (.lattices.json)

Declare panes, commands, and layout per project. lattices start builds/attaches a persistent session named <basename>-<hash>; lattices sync reconciles a running session to its config. Ensure re-runs exited commands on reattach; prefill types them and waits. → Concepts, Configuration.

Screen OCR & search

The app reads on-screen text via the Accessibility API (~60s) and Apple Vision OCR on background windows (~2h), indexing everything with FTS5. Search across titles, app names, session tags, and OCR with lattices search <query> (add --deep or --all to inspect terminal tabs by cwd). → Screen OCR & Search.

Voice commands

Natural-language voice control for window management ("put the browser on the right", "switch to the backend layer"). → Voice Commands.

Mouse gestures

Hold a mouse button, draw a direction or shape, release — runs the matched action. Configured via mouseGestures.enabled plus ~/.lattices/mouse-shortcuts.json. → Mouse Gestures.

Agent API & CLI

Agents connect over WebSocket and get the same control as a person: list windows/projects, launch sessions, tile, switch layers, read screen text, and subscribe to events (windows.changed, tmux.changed, layer.switched). → Agent Guide, Agent API.

Key shortcuts

Tiling and grid hotkeys are user-configurable — for the live set, point the user to Settings or the Tiling reference rather than treating the defaults as guaranteed.

CLI quick reference

lattices · lattices init · lattices sync · lattices start · lattices restart [pane] · lattices tile <position> · lattices group [id] · lattices layer [name|index] · lattices windows --json · lattices search <query> [--deep|--all] [--json] [--wid] · lattices place <query> [position] · lattices app restart. Full flags: Configuration.

Config & file locations

• Per project: .lattices.json in the project root (panes, commands, layout, ensure/prefill).
• User config (~/.lattices/): workspace.json, layers.json, mouse-shortcuts.json, snap-zones.json, clusters.json, ocr.db, lattices.log.
• Defaults domain: dev.lattices.app (read/write app settings via defaults).

The exact current values and paths for this machine arrive in your structured context — prefer those over the generic paths above when answering.

References