lattices
Lattices documentation

Getting started

Install Lattices, tile a window, find a window, and start a project session in your first ten minutes

Updated Edit on GitHub →

After this page you can tile a window with a key, find and place a window from a terminal, and start a terminal session for a project. Each step says what to expect and what to do if it does not happen.

Requirements: a Mac on macOS 26 or later and Bun. tmux is needed only for step 6.

The examples use an invented project, tideline, checked out at ~/dev/tideline. Substitute your own project.

1. Install the app and the CLI

Install the app with Homebrew:

brew tap arach/tap
brew trust arach/tap
brew install --cask arach/tap/lattices

Or download the disk image from the latest release and drag Lattices.app to /Applications.

Install the CLI:

bun install -g @lattices/lattices

npm install -g @lattices/lattices also works. The CLI still needs Bun at runtime.

Check:

lats help

Expected: the command reference prints. If the shell reports command not found, add Bun's global bin directory to PATH and open a new shell.

2. Launch the app

lats app

Expected: a Lattices icon appears in the menu bar and macOS asks for Accessibility access. Grant it in System Settings > Privacy & Security > Accessibility. Lattices moves windows through the Accessibility API, so nothing tiles until this permission is on.

Check that the CLI can reach the app:

lats daemon status

Expected: a status line with the daemon's version. If the CLI prints Daemon not running, the app is not running or has not finished starting. Run lats app again and retry.

Start the app at login, if you want it:

lats app install

3. Tile a window with a key

  1. Click any window to bring it to the front.
  2. Press Control+Option+Right.

Expected: the window fills the right half of its display, below the menu bar and above the Dock. Control+Option+Left, Up and Down place the other halves.

If nothing moves, open System Settings > Privacy & Security > Accessibility and confirm Lattices is listed and on. Then try again.

4. Open the command bar

Press Control+Option+Space.

Expected: the command bar opens. Type part of a window title, an app name or a project name. Press Return to go to the top result. Press Escape to close the bar.

The command bar is the fastest way to reach a window on another Space or display. It also lists projects, layers and app commands.

5. Find and place a window from the terminal

Search for a window by any word in its title or app name:

lats search chrome

Expected: a ranked list of matching windows with their window ids. If the output is No results for "chrome", try a word from a window title you can see.

Find the top match and tile it in one step:

lats place chrome left

Expected: the best-matching Chrome window comes to the front and fills the left half. Without a position, lats place uses bottom-right.

lats tile <position> moves the front window without a search:

lats tile right
lats tile top-left
lats tile maximize

Tiling and placement lists every position.

6. Start a session for a project

This step needs tmux:

brew install tmux

Write a config for the project and start it:

cd ~/dev/tideline
lats init
lats start

Expected: lats init prints Created .lattices.json and the config it wrote. For a project with a dev script in package.json, the config has two panes: a shell on the left at 60% width and the dev server on the right. lats start attaches your terminal to a tmux session named tideline-<hash>, where <hash> comes from the directory path.

Detach with Ctrl+B then D. Run lats start again from the same directory to reattach. The dev server keeps running in between.

If lats init prints .lattices.json already exists., the project already has a config. lats start uses it.

Sessions explains the config file and the session lifecycle.

7. Turn on screen-text search (optional)

With screen-text search on, lats search and the command bar also match words that are visible inside windows, such as an error message in a terminal.

  1. Open System Settings > Privacy & Security > Screen Recording and turn Lattices on.
  2. Open Lattices Settings from the menu bar and turn on Search & OCR.

Expected: within about a minute, lats scan prints text from the visible windows. Finding windows covers the search tiers.

Where to go next