@arach/lattices 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +95 -84
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,9 +4,12 @@
4
4
 
5
5
  # lattices
6
6
 
7
- Declarative tmux sessions for developers.
7
+ macOS workspace manager. Menu bar app, CLI, and a WebSocket API
8
+ so your AI agents can control the desktop.
8
9
 
9
- One command to create a named tmux session with your tools running. Auto-detects your stack, fully configurable with `.lattices.json`, and a native macOS menu bar app.
10
+ Window tiling, project discovery, workspace layers, on-screen OCR,
11
+ and optionally tmux-powered persistent sessions. 30 RPC methods
12
+ over WebSocket. One JSON config file.
10
13
 
11
14
  ## Install
12
15
 
@@ -17,19 +20,45 @@ npm install -g @arach/lattices
17
20
  ## Quick start
18
21
 
19
22
  ```sh
20
- cd my-project
21
- lattices
23
+ # Launch the menu bar app
24
+ lattices app
25
+
26
+ # Open the command palette from anywhere
27
+ # Cmd+Shift+M
28
+ ```
29
+
30
+ The app scans your projects, tiles windows, and gives you a command
31
+ palette for everything. Add tmux if you want persistent terminal
32
+ sessions:
33
+
34
+ ```sh
35
+ brew install tmux
36
+ cd my-project && lattices
22
37
  ```
23
38
 
24
- That's it. lattices creates a tmux session named after your project with Claude Code on the left and your dev server on the right. It detects your package manager and dev command automatically.
39
+ That creates a tmux session with Claude Code on the left and your
40
+ dev server on the right. Detach, close your laptop, come back later,
41
+ reattach. Everything is where you left it.
42
+
43
+ ## What it does
44
+
45
+ **Menu bar app** sits in your menu bar. Command palette, window tiling,
46
+ project discovery, workspace layers, OCR, and the daemon API. Works
47
+ with or without tmux.
48
+
49
+ **CLI** for tiling, session management, OCR queries, and tab groups.
25
50
 
26
- ## How it works
51
+ **Daemon API** on `ws://127.0.0.1:9399`. 30 RPC methods and 5
52
+ real-time events. Agents can discover projects, tile windows, launch
53
+ sessions, switch layers, and read on-screen text.
27
54
 
28
- 1. **Run `lattices`** in any project directory
29
- 2. A named tmux session is created with configured panes
30
- 3. Commands start running in each pane immediately
31
- 4. Detach with `Ctrl+b d`, reattach by running `lattices` again
32
- 5. Sessions persist in the background until you kill them
55
+ ```js
56
+ import { daemonCall } from '@arach/lattices/daemon-client'
57
+
58
+ const windows = await daemonCall('windows.list')
59
+ await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
60
+ await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
61
+ ```
33
62
 
34
63
  ## Configuration
35
64
 
@@ -46,111 +75,93 @@ Drop a `.lattices.json` in your project root:
46
75
  }
47
76
  ```
48
77
 
49
- ### Pane options
50
-
51
- | Field | Description |
52
- |--------|------------------------------------------|
53
- | `name` | Label for the pane (for your reference) |
54
- | `cmd` | Command to run in the pane |
55
- | `size` | Width % for the first pane (default: 60) |
56
-
57
- ### Session options
58
-
59
- | Field | Description |
60
- |-----------|-----------------------------------------------------------------------------|
61
- | `ensure` | Auto-restart exited commands on reattach |
62
- | `prefill` | Type exited commands into panes on reattach without running (you hit Enter) |
78
+ Or skip it. Without a config, lattices reads your `package.json` and
79
+ picks the right dev command automatically.
63
80
 
64
81
  ### Layouts
65
82
 
66
83
  ```
67
- 2 panes — side-by-side 3+ panes — main-vertical
68
-
69
- ┌──────────┬─────────┐ ┌──────────┬─────────┐
70
- │ claude │ server │ │ claude │ server │
71
- │ (60%) │ (40%) │ │ (60%) ├─────────┤
72
- └──────────┴─────────┘ │ │ tests │
73
- └──────────┴─────────┘
74
- ```
75
-
76
- ## Auto-detection
84
+ 2 panes 3+ panes
77
85
 
78
- Without a config file, lattices reads your `package.json` and picks the right command:
79
-
80
- - Checks `scripts.dev`, `scripts.start`, `scripts.serve`, `scripts.watch`
81
- - Detects package manager from lock files (pnpm, bun, yarn, npm)
82
- - Falls back to a shell if no dev command is found
83
-
84
- ## Menu bar app
85
-
86
- A macOS companion app for managing sessions without touching the terminal.
87
-
88
- ```sh
89
- lattices app # Launch (builds from source or downloads binary)
90
- lattices app build # Force rebuild from source
91
- lattices app quit # Stop the menu bar app
86
+ ┌──────────┬───────┐ ┌──────────┬───────┐
87
+ │ claude │server │ │ claude │server │
88
+ │ (60%) │(40%) │ │ (60%) ├───────┤
89
+ └──────────┴───────┘ │ │tests │
90
+ └──────────┴───────┘
92
91
  ```
93
92
 
94
- Features:
95
- - See all projects and their session status at a glance
96
- - Launch, attach, or detach sessions with a click
97
- - **Command palette** (`Cmd+Shift+M`): Raycast-style launcher for all actions — fuzzy search, keyboard navigation, instant access to projects, window tiling, and settings
98
- - Auto-scans your project directories
99
- - Built with SwiftUI, runs natively on macOS
100
-
101
- The app tries to compile from source first (requires Xcode CLI tools), falling back to a pre-built arm64 binary from GitHub releases.
93
+ ## Workspace layers
102
94
 
103
- ## Tab groups
95
+ Group projects into switchable contexts. `Cmd+Option+1` tiles your
96
+ frontend and API side by side. `Cmd+Option+2` switches to the mobile
97
+ stack. All sessions stay alive across switches.
104
98
 
105
- Bundle related projects as tabs within a single terminal window.
106
99
  Configure in `~/.lattices/workspace.json`:
107
100
 
108
101
  ```json
109
102
  {
110
- "name": "my-setup",
111
- "groups": [
103
+ "layers": [
112
104
  {
113
- "id": "talkie",
114
- "label": "Talkie",
115
- "tabs": [
116
- { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
117
- { "path": "/Users/you/dev/talkie-web", "label": "Website" },
118
- { "path": "/Users/you/dev/talkie-api", "label": "API" }
105
+ "id": "web", "label": "Web",
106
+ "projects": [
107
+ { "path": "/Users/you/dev/frontend", "tile": "left" },
108
+ { "path": "/Users/you/dev/api", "tile": "right" }
119
109
  ]
120
110
  }
121
111
  ]
122
112
  }
123
113
  ```
124
114
 
125
- Each tab gets its own tmux window with pane layout from its `.lattices.json`.
115
+ ## Tab groups
116
+
117
+ Bundle related repos as tabs in one session. Each tab gets its own
118
+ pane layout from its `.lattices.json`.
126
119
 
127
120
  ```sh
128
- lattices groups # List groups with status
129
- lattices group talkie # Launch or attach
130
- lattices tab talkie iOS # Switch to a tab
121
+ lattices group talkie # Launch iOS, macOS, Web, API as tabs
122
+ lattices tab talkie iOS # Switch to the iOS tab
131
123
  ```
132
124
 
133
- Groups can also be referenced in [workspace layers](https://lattices.dev/docs/layers) to tile a whole group into a screen position.
125
+ ## Screen OCR
126
+
127
+ The app reads text from visible windows using Apple Vision and indexes
128
+ it with FTS5 full-text search. Agents can search for error messages,
129
+ read terminal output, or find content across all your windows.
130
+
131
+ ```js
132
+ await daemonCall('ocr.scan')
133
+ const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
134
+ ```
134
135
 
135
- ## CLI reference
136
+ ## CLI
136
137
 
137
138
  ```
138
- lattices Create or reattach to a session for the current project
139
- lattices init Generate a .lattices.json config
140
- lattices ls List active tmux sessions
141
- lattices kill [name] Kill a session (defaults to current project)
142
- lattices group [id] List tab groups or launch/attach a group
143
- lattices groups List all tab groups with status
144
- lattices tab <group> [tab] Switch tab within a group (by label or index)
145
- lattices app Launch the menu bar companion app
139
+ lattices Create or reattach to session
140
+ lattices init Generate .lattices.json
141
+ lattices ls List active sessions
142
+ lattices kill [name] Kill a session
143
+ lattices tile <position> Tile frontmost window
144
+ lattices group [id] Launch or attach a tab group
145
+ lattices tab <group> [tab] Switch tab within a group
146
+ lattices ocr View current OCR snapshot
147
+ lattices ocr search <query> Search OCR history
148
+ lattices app Launch the menu bar app
146
149
  lattices help Show help
147
150
  ```
148
151
 
149
152
  ## Requirements
150
153
 
151
- - **tmux** — `brew install tmux`
152
- - **Node.js** 18+
153
- - **macOS** (the CLI is macOS-only, the menu bar app requires arm64)
154
+ - macOS 13.0+
155
+ - Node.js 18+
156
+
157
+ ### Optional
158
+
159
+ - tmux for persistent terminal sessions (`brew install tmux`)
160
+ - Swift 5.9+ to build the menu bar app from source
161
+
162
+ ## Docs
163
+
164
+ Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview).
154
165
 
155
166
  ## License
156
167
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arach/lattices",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "macOS workspace manager with window tiling, OCR, and a 30-method daemon API for AI agents",
5
5
  "bin": {
6
6
  "lattices": "./bin/lattices.js",