lattices

macOS workspace manager. Menu bar app, CLI, and a WebSocket API so your AI agents can control the desktop.

Window tiling, project discovery, workspace layers, on-screen OCR, and optionally tmux-powered persistent sessions. 30 RPC methods over WebSocket. One JSON config file.

Install

npm install -g @arach/lattices

Quick start

# Launch the menu bar app
lattices app

# Open the command palette from anywhere
# Cmd+Shift+M

The app scans your projects, tiles windows, and gives you a command palette for everything. Add tmux if you want persistent terminal sessions:

brew install tmux
cd my-project && lattices

That creates a tmux session with Claude Code on the left and your dev server on the right. Detach, close your laptop, come back later, reattach. Everything is where you left it.

What it does

Menu bar app sits in your menu bar. Command palette, window tiling, project discovery, workspace layers, OCR, and the daemon API. Works with or without tmux.

CLI for tiling, session management, OCR queries, and tab groups.

Daemon API on ws://127.0.0.1:9399. 30 RPC methods and 5 real-time events. Agents can discover projects, tile windows, launch sessions, switch layers, and read on-screen text.

import { daemonCall } from '@arach/lattices/daemon-client'

const windows = await daemonCall('windows.list')
await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })

Configuration

Drop a .lattices.json in your project root:

{
  "ensure": true,
  "panes": [
    { "name": "claude", "cmd": "claude", "size": 60 },
    { "name": "server", "cmd": "pnpm dev" },
    { "name": "tests",  "cmd": "pnpm test --watch" }
  ]
}

Or skip it. Without a config, lattices reads your package.json and picks the right dev command automatically.

Layouts

2 panes              3+ panes

┌──────────┬───────┐ ┌──────────┬───────┐
│  claude  │server │ │  claude  │server │
│  (60%)   │(40%)  │ │  (60%)   ├───────┤
└──────────┴───────┘ │          │tests  │
                     └──────────┴───────┘

Workspace layers

Group projects into switchable contexts. Cmd+Option+1 tiles your frontend and API side by side. Cmd+Option+2 switches to the mobile stack. All sessions stay alive across switches.

Configure in ~/.lattices/workspace.json:

{
  "layers": [
    {
      "id": "web", "label": "Web",
      "projects": [
        { "path": "/Users/you/dev/frontend", "tile": "left" },
        { "path": "/Users/you/dev/api", "tile": "right" }
      ]
    }
  ]
}

Tab groups

Bundle related repos as tabs in one session. Each tab gets its own pane layout from its .lattices.json.

lattices group talkie      # Launch iOS, macOS, Web, API as tabs
lattices tab talkie iOS    # Switch to the iOS tab

Screen OCR

The app reads text from visible windows using Apple Vision and indexes it with FTS5 full-text search. Agents can search for error messages, read terminal output, or find content across all your windows.

await daemonCall('ocr.scan')
const errors = await daemonCall('ocr.search', { query: 'error OR failed' })

CLI

lattices                    Create or reattach to session
lattices init               Generate .lattices.json
lattices ls                 List active sessions
lattices kill [name]        Kill a session
lattices tile <position>    Tile frontmost window
lattices group [id]         Launch or attach a tab group
lattices tab <group> [tab]  Switch tab within a group
lattices ocr                View current OCR snapshot
lattices ocr search <query> Search OCR history
lattices app                Launch the menu bar app
lattices help               Show help

Requirements

• macOS 13.0+
• Node.js 18+

Optional

• tmux for persistent terminal sessions (brew install tmux)
• Swift 5.9+ to build the menu bar app from source

Docs

Full documentation at lattices.dev/docs.

License

MIT