Agent API

The lattices menu bar app runs a WebSocket server on ws://127.0.0.1:9399. 35+ RPC methods and 5 real-time events.

Quick start

1. Launch the server (it starts with the menu bar app):

lattices app

2. Check that it's running:

lattices daemon status

3. Call a method from Node.js:

const windows = await daemonCall('windows.list')
console.log(windows) // [{ wid, app, title, frame, ... }, ...]

Or from any language — it's a standard WebSocket:

# Plain websocat example
echo '{"id":"1","method":"daemon.status"}' | websocat ws://127.0.0.1:9399

Wire protocol

lattices uses a JSON-RPC-style protocol over WebSocket on port 9399.

Request

{
  "id": "unique-string",
  "method": "windows.list",
  "params": { "wid": 1234 }
}

Response

{
  "id": "unique-string",
  "result": [ ... ],
  "error": null
}

Errors

Connection lifecycle

• The server starts when the menu bar app launches and stops when it quits.
• Connections are plain WebSocket. No handshake, no auth, no heartbeat.
• The Node.js daemonCall() client opens a fresh connection per call and closes it when the response arrives. For event subscriptions, hold the connection open (see Reactive event pattern).
• If the server restarts (e.g. after lattices app restart), existing connections are dropped. Clients should reconnect and treat it as stateless. There is no session resumption.

Node.js client

lattices ships a zero-dependency WebSocket client that works with Node.js 18+. It handles connection, framing, and request/response matching internally.

daemonCall(method, params?, timeoutMs?)

Send an RPC call and await the response.

// Read-only
const status = await daemonCall('daemon.status')
const windows = await daemonCall('windows.list')
const win = await daemonCall('windows.get', { wid: 1234 })

// Mutations
await daemonCall('session.launch', { path: '/Users/you/dev/myapp' })
await daemonCall('window.place', {
  session: 'myapp-a1b2c3',
  placement: { kind: 'tile', value: 'left' }
})

// Custom timeout (default: 3000ms)
await daemonCall('projects.scan', null, 10000)

Returns the result field from the response. Throws if the server returns an error, the connection fails, or the timeout is reached.

isDaemonRunning()

Check if the server is reachable.

if (await isDaemonRunning()) {
  console.log('daemon is up')
}

Returns true if daemon.status responds within 1 second.

Error handling

daemonCall throws on errors — always wrap calls in try/catch:

try {
  await daemonCall('session.launch', { path: '/nonexistent' })
} catch (err) {
  // err.message is one of:
  //   "Not found"              — resource doesn't exist
  //   "Missing parameter: ..." — required param missing
  //   "Unknown method: ..."    — bad method name
  //   "Daemon request timed out" — no response within timeout
  //   ECONNREFUSED             — daemon not running
  console.error('Daemon error:', err.message)
}

Overlay UI

The macOS app exposes a shared desktop overlay canvas for lightweight agent-visible UI. Use overlay.publish for transient passive visuals, and overlay.actor.* for persistent, movable actor surfaces.

Persistent actors are useful for representing agents or processes on the desktop. Each actor has a stable id, can be moved independently through the API, dragged by the user, hidden/restored with Hyper+8, and closed with right-click. Click event callbacks and action surfaces are planned follow-on capabilities.

overlay.publish

Publish a transient layer on the screen overlay canvas.

Params:

Example:

await daemonCall('overlay.publish', {
  kind: 'highlight',
  x: 160,
  y: 120,
  w: 480,
  h: 260,
  text: 'Needs review',
  style: 'warning',
  ttlMs: 3000
})

overlay.actor.publish

Create or update a generative overlay actor. Actors default to persistent: omit ttlMs or pass 0, and dismissible defaults to false.

Params:

Bundled sprite assets:

Example:

await daemonCall('overlay.actor.publish', {
  id: 'agent-scout',
  renderer: 'sprite',
  asset: 'scout-ranger',
  state: 'waiting',
  name: 'Scout',
  message: 'Waiting for feedback',
  placement: 'point',
  x: 640,
  y: 320,
  ttlMs: 0
})

overlay.actor.moveTo

Move an actor with app-owned animation. The app interpolates position and switches directional sprite states while moving.

Params:

Example:

await daemonCall('overlay.actor.moveTo', {
  id: 'agent-scout',
  x: 820,
  y: 280,
  durationMs: 800,
  easing: 'spring'
})

System

deck.manifest

Return the shared DeckKit manifest exposed by the macOS app. This is the contract a future Lattices companion can consume to discover pages, capabilities, and security mode.

Params: none

deck.snapshot

Return the current DeckKit runtime snapshot for the macOS host.

Params: none

Returns: a DeckRuntimeSnapshot object containing:

• voice
• desktop
• switcher
• history
• questions

deck.perform

Perform a DeckKit action against the running macOS host and return a DeckActionResult.

Params:

Example:

{
  "id": "1",
  "method": "deck.perform",
  "params": {
    "pageID": "layout",
    "actionID": "layout.optimize",
    "payload": {
      "strategy": "balanced",
      "region": "right"
    }
  }
}

daemon.status

Health check and basic stats.

Params: none

Returns:

{
  "uptime": 3600.5,
  "clientCount": 2,
  "version": "1.0.0",
  "windowCount": 12,
  "tmuxSessionCount": 3
}

api.schema

Return the full API schema including version, models, and method definitions. Useful for agent self-discovery.

Params: none

CLI shortcut:

lattices call api.schema

diagnostics.list

Return recent diagnostic log entries from the daemon.

Params:

Windows & Spaces

windows.list

List all visible windows tracked by the desktop model.

Params: none

Returns: array of window objects:

[
  {
    "wid": 1234,
    "app": "Terminal",
    "pid": 5678,
    "title": "[lattices:myapp-a1b2c3] zsh",
    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
    "spaceIds": [1],
    "isOnScreen": true,
    "latticesSession": "myapp-a1b2c3",
    "layerTag": "web"
  }
]

The latticesSession field is present only on windows that belong to a lattices session (matched via the [lattices:name] title tag).

The layerTag field is present when a window has been manually assigned to a layer via window.assignLayer.

windows.get

Get a single window by its CGWindowID.

Params:

Returns: a single window object (same shape as windows.list items). Errors: Not found if the window ID doesn't exist.

windows.search

Search windows by text query across title, app name, session tags, and OCR content. Returns results with matchSource indicating how the match was found, and ocrSnippet for OCR matches.

Params:

Returns: array of window objects with additional search fields:

[
  {
    "wid": 265,
    "app": "iTerm2",
    "title": "✳ Claude Code",
    "matchSource": "ocr",
    "ocrSnippet": "…~/dev/vox StatusBarIconFolder…",
    "frame": { "x": 688, "y": 3, "w": 1720, "h": 720 },
    "isOnScreen": true
  }
]

matchSource values: "title", "app", "session", "ocr".

CLI usage:

# Basic search (uses windows.search)
lattices search vox

# Deep search — adds terminal tab/process inspection for ranking
lattices search vox --deep

# Pipeable output
lattices search vox --wid
lattices search vox --json

# Search + focus + tile in one step
lattices place vox right

spaces.list

List macOS display spaces (virtual desktops).

Params: none

Returns: array of display objects:

[
  {
    "displayIndex": 0,
    "displayId": "main",
    "currentSpaceId": 1,
    "spaces": [
      { "id": 1, "index": 0, "display": 0, "isCurrent": true },
      { "id": 2, "index": 1, "display": 0, "isCurrent": false }
    ]
  }
]

window.place

Canonical window placement mutation. Use this when an agent needs a single, typed placement contract across voice, CLI, and daemon clients.

Params:

Target resolution priority is wid → session → app/title → frontmost window.

Placement strings: left, right, top, bottom, top-left, top-right, bottom-left, bottom-right, left-third, center-third, right-third, top-third, middle-third, bottom-third, left-quarter, right-quarter, top-quarter, bottom-quarter, maximize, center, or grid:CxR:C,R.

Typed placement examples:

{ "kind": "tile", "value": "top-right" }
{ "kind": "grid", "columns": 3, "rows": 2, "column": 2, "row": 0 }
{ "kind": "fractions", "x": 0.5, "y": 0, "w": 0.5, "h": 1 }

Returns: execution receipt including resolved target, placement, and trace.

window.tile

Compatibility wrapper for window.place when the target is a lattices session window.

Params:

This method exists for compatibility. New integrations should prefer window.place.

window.focus

Focus a window — bring it to front and switch Spaces if needed.

Params (one of):

Provide either wid or session. If wid is given, it takes priority.

window.move

Move a session's window to a different macOS Space.

Params:

window.assignLayer

Manually tag a window to a layer. Tagged windows are raised and tiled when that layer activates, even if they aren't declared in workspace.json.

Params:

window.removeLayer

Remove a window's layer tag.

Params:

window.layerMap

Return all current window→layer assignments.

Params: none

Returns:

{
  "1234": "web",
  "5678": "mobile"
}

Keys are CGWindowIDs (as strings), values are layer IDs.

space.optimize

Canonical space-balancing mutation. Use this when the goal is to make the current workspace coherent rather than placing one specific window.

Params:

If windowIds is provided, scope is inferred as selection. If app is provided and scope is omitted, scope is inferred as app.

Returns: execution receipt including resolved scope, strategy, affected window IDs, and trace.

layout.distribute

Compatibility wrapper for space.optimize with scope=visible and strategy=balanced.

Params: none

Sessions

All session methods require tmux to be installed.

tmux.sessions

List tmux sessions that belong to lattices.

Params: none

Returns: array of session objects:

[
  {
    "name": "myapp-a1b2c3",
    "windowCount": 1,
    "attached": true,
    "panes": [
      {
        "id": "%0",
        "windowIndex": 0,
        "windowName": "main",
        "title": "claude",
        "currentCommand": "claude",
        "pid": 9876,
        "isActive": true
      }
    ]
  }
]

tmux.inventory

List all tmux sessions including orphans (sessions not tracked by lattices).

Params: none

Returns:

{
  "all": [ ... ],
  "orphans": [ ... ]
}

Both arrays contain session objects (same shape as tmux.sessions).

session.launch

Launch a new tmux session for a project. If a session already exists, it will be reattached. The project must be in the scanned project list — call projects.list to check, or projects.scan to refresh.

Params:

Returns: { "ok": true } Errors: Not found if the path isn't in the scanned project list.

session.kill

Kill a tmux session by name.

Params:

session.detach

Detach all clients from a session (keeps it running).

Params:

session.sync

Reconcile a running session to match its declared .lattices.json config. Recreates missing panes, re-applies layout, restores labels, re-runs commands in idle panes.

Params:

Errors: Not found if the path isn't in the project list.

session.restart

Restart a specific pane's process within a session.

Params:

Projects & Layers

projects.list

List all discovered projects.

Params: none

Returns: array of project objects:

[
  {
    "path": "/Users/you/dev/myapp",
    "name": "myapp",
    "sessionName": "myapp-a1b2c3",
    "isRunning": true,
    "hasConfig": true,
    "paneCount": 2,
    "paneNames": ["claude", "server"],
    "devCommand": "pnpm dev",
    "packageManager": "pnpm"
  }
]

devCommand and packageManager are present only when detected.

projects.scan

Trigger a re-scan of the project directory. Useful after cloning a new repo or adding a .lattices.json config.

Params: none

layers.list

List configured workspace layers and the active index.

Params: none

Returns:

{
  "layers": [
    { "id": "web", "label": "Web", "index": 0, "projectCount": 2 },
    { "id": "mobile", "label": "Mobile", "index": 1, "projectCount": 2 }
  ],
  "active": 0
}

Returns empty layers array if no workspace config is loaded.

layer.activate

Canonical layer mutation. Use this when an agent wants an explicit activation mode instead of implicit "switch" behavior.

Params:

Provide either index or name.

Modes:

• launch — bring up the layer, launching missing projects and retiling
• focus — raise the layer's windows in place
• retile — re-apply the layer layout without launch semantics

Returns: execution receipt including resolved layer, mode, and trace.

layer.switch

Compatibility wrapper for layer.activate with mode=launch. It keeps the old semantics and still posts a layer.switched event.

group.launch

Launch a tab group session.

Params:

Errors: Not found if the group ID doesn't match any configured group.

group.kill

Kill a tab group session.

Params:

Processes & Terminals

processes.list

List running processes relevant to development (editors, servers, build tools).

Params:

Returns: array of process objects:

[
  {
    "pid": 1234,
    "ppid": 567,
    "command": "node",
    "args": "server.js",
    "cwd": "/Users/you/dev/myapp",
    "tty": "/dev/ttys003",
    "tmuxSession": "myapp-a1b2c3",
    "tmuxPaneId": "%0"
  }
]

processes.tree

Get the process tree rooted at a given PID.

Params:

Returns: array of process objects (same shape as processes.list).

terminals.list

List all discovered terminal instances with their processes, tabs, and tmux associations.

Params:

Returns: array of terminal instance objects:

[
  {
    "tty": "/dev/ttys003",
    "app": "Terminal",
    "windowIndex": 0,
    "tabIndex": 0,
    "isActiveTab": true,
    "tabTitle": "myapp",
    "processes": [ ... ],
    "shellPid": 1234,
    "cwd": "/Users/you/dev/myapp",
    "tmuxSession": "myapp-a1b2c3",
    "tmuxPaneId": "%0",
    "hasClaude": true,
    "displayName": "Terminal — myapp"
  }
]

terminals.search

Search terminal instances by various criteria.

Params:

Returns: filtered array of terminal instance objects (same shape as terminals.list).

OCR

See Screen OCR for configuration, scan schedules, and storage details.

ocr.snapshot

Get the current in-memory OCR results for all visible windows.

Params: none

Returns: array of OCR result objects:

[
  {
    "wid": 1234,
    "app": "Terminal",
    "title": "zsh",
    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
    "fullText": "~/dev/myapp $ npm run dev\nready on port 3000",
    "blocks": [
      {
        "text": "~/dev/myapp $ npm run dev",
        "confidence": 0.95,
        "x": 0.02, "y": 0.05, "w": 0.6, "h": 0.04
      }
    ],
    "timestamp": 1709568000.0
  }
]

ocr.search

Full-text search across OCR history using SQLite FTS5.

Params:

FTS5 query examples: error, "build failed", error OR warning, npm AND dev, react*

ocr.history

Get the OCR timeline for a specific window, ordered by most recent first.

Params:

ocr.scan

Trigger an immediate OCR scan of all visible windows, bypassing the periodic timer. Results available via ocr.snapshot once complete; an ocr.scanComplete event is broadcast to all clients.

Params: none

Events

Events are pushed to all connected WebSocket clients when state changes. They have no id field — listen for messages with an event field.

windows.changed

{ "event": "windows.changed", "data": { "windowCount": 12, "added": [1234], "removed": [5678] } }

tmux.changed

{ "event": "tmux.changed", "data": { "sessionCount": 3, "sessions": ["myapp-a1b2c3"] } }

layer.switched

{ "event": "layer.switched", "data": { "index": 1, "name": "mobile" } }

ocr.scanComplete

{ "event": "ocr.scanComplete", "data": { "windowCount": 12, "totalBlocks": 342 } }

processes.changed

{ "event": "processes.changed", "data": { "interestingCount": 5, "pids": [1234, 5678] } }

Agent integration

CLAUDE.md snippet

Add this to your project's CLAUDE.md so any AI agent working in the project knows how to control the workspace:

## Workspace Control

This project uses lattices for workspace management. The daemon API
is available at ws://127.0.0.1:9399.

### Search (find windows)
- Search by content: `daemonCall('windows.search', { query: 'myproject' })`
  Returns windows with `matchSource` ("title", "app", "session", "ocr") and `ocrSnippet`
- Search terminals: `daemonCall('terminals.search', {})` — tabs, cwds, processes
- CLI: `lattices search myproject` or `lattices search myproject --deep`

### Actions
- Focus a window: `daemonCall('window.focus', { wid: 1234 })`
- Place a window: `daemonCall('window.place', { session: 'name', placement: 'left' })`
- Launch a project: `daemonCall('session.launch', { path: '/absolute/path' })`
- Activate a layer: `daemonCall('layer.activate', { name: 'web', mode: 'launch' })`
- Optimize the workspace: `daemonCall('space.optimize', { scope: 'visible', strategy: 'balanced' })`
- CLI: `lattices place myproject left` (search + focus + tile in one step)

### Import
\```js

\```

Multi-agent orchestration

An orchestrator agent can set up the full workspace for sub-agents:

// Discover what's available
const projects = await daemonCall('projects.list')

// Launch the projects we need
await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
await daemonCall('session.launch', { path: '/Users/you/dev/api' })

// Tile them side by side
const sessions = await daemonCall('tmux.sessions')
const fe = sessions.find(s => s.name.startsWith('frontend'))
const api = sessions.find(s => s.name.startsWith('api'))

await daemonCall('window.place', { session: fe.name, placement: 'left' })
await daemonCall('window.place', { session: api.name, placement: 'right' })

Reactive event pattern

Subscribe to events to react to workspace changes:

const ws = new WebSocket('ws://127.0.0.1:9399')

ws.on('message', (raw) => {
  const msg = JSON.parse(raw)

  if (msg.event === 'tmux.changed') {
    console.log('Sessions:', msg.data.sessions.join(', '))
  }

  if (msg.event === 'windows.changed') {
    console.log('Windows:', msg.data.windowCount, 'total')
  }

  if (msg.event === 'layer.switched') {
    console.log('Switched to layer', msg.data.index)
  }
})

// You can also send RPC calls on the same connection
ws.on('open', () => {
  ws.send(JSON.stringify({ id: '1', method: 'daemon.status' }))
})

Health check before use

Always verify the daemon is running before making calls:

if (!(await isDaemonRunning())) {
  console.error('lattices daemon is not running — start it with: lattices app')
  process.exit(1)
}

const status = await daemonCall('daemon.status')
console.log(`Daemon up for ${Math.round(status.uptime)}s, tracking ${status.windowCount} windows`)