@lattices/cli 0.3.0 → 0.4.1

package/README.md

@@ -4,16 +4,62 @@
 
 # lattices
 
-A workspace control plane for macOS. Manage persistent terminal sessions,
-tile and organize your windows, and index the text on your screen — all
-controllable from the CLI or a 30-method daemon API.
+The agentic window manager for macOS.
+
+Tile windows with hotkeys, manage persistent tmux sessions, index screen
+text with OCR, and give AI agents a 35-method desktop API — all from a
+native menu bar app and CLI.
+
+**[lattices.dev](https://lattices.dev)** · [Docs](https://lattices.dev/docs/overview) · [Download](https://github.com/arach/lattices/releases/latest)
 
 ## Install
 
+### Download the app
+
+Grab the signed DMG from the [latest release](https://github.com/arach/lattices/releases/latest):
+
+```sh
+# Or direct download:
+curl -LO https://github.com/arach/lattices/releases/latest/download/Lattices.dmg
+open Lattices.dmg
+```
+
+Drag **Lattices.app** into Applications. On first launch, a setup wizard
+walks you through granting Accessibility, Screen Recording, and choosing
+your project directory.
+
+### Install the CLI
+
 ```sh
 npm install -g @lattices/cli
 ```
 
+The CLI and app work independently — use either or both.
+
+### Build from source
+
+```sh
+git clone https://github.com/arach/lattices.git
+cd lattices
+
+# Build the menu bar app (requires Swift 5.9+ / Xcode 15+)
+cd app && swift build -c release && cd ..
+
+# Install CLI dependencies
+npm install
+
+# Launch
+node bin/lattices-app.js build   # bundle the .app
+node bin/lattices-app.js         # launch it
+```
+
+To build a signed, notarized DMG for distribution:
+
+```sh
+# Requires a Developer ID certificate and notarytool keychain profile
+./scripts/build-dmg.sh
+```
+
 ## Quick start
 
 ```sh
@@ -77,8 +123,8 @@ Bundle related repos as tabs in one session. Each tab gets its own
 pane layout from its `.lattices.json`.
 
 ```sh
-lattices group talkie      # Launch iOS, macOS, Web, API as tabs
-lattices tab talkie iOS    # Switch to the iOS tab
+lattices group vox         # Launch iOS, macOS, Web, API as tabs
+lattices tab vox iOS       # Switch to the iOS tab
 ```
 
 ## Window tiling and awareness
@@ -97,16 +143,31 @@ lattices scan recent           # Browse scan history
 lattices scan deep             # Trigger a Vision OCR scan now
 ```
 
+## Voice commands (beta)
+
+Speak to control your workspace — tile windows, search, focus apps,
+and launch projects with natural language. Powered by
+[Vox](https://github.com/arach/vox) for transcription and
+local NLEmbedding for intent matching, with Claude fallback for
+ambiguous commands.
+
+Trigger with `Hyper+3` (configurable). Press Space to speak, Space to
+stop. The panel shows what was heard, the matched intent, extracted
+parameters, and execution results.
+
 ## A programmable desktop
 
-The menu bar app runs a daemon with 30 RPC methods and 5 real-time
+The menu bar app runs a daemon with 35 RPC methods and 5 real-time
 events over WebSocket. Anything you can do from the app, an agent or
 script can do over the API.
 
 ```js
 import { daemonCall } from '@lattices/cli/daemon-client'
 
-const windows = await daemonCall('windows.list')
+// Search windows by content — title, app, session tags, OCR
+const results = await daemonCall('windows.search', { query: 'myproject' })
+
+// Launch and tile
 await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
 await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
 
@@ -115,6 +176,14 @@ await daemonCall('ocr.scan')
 const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
 ```
 
+Or from the CLI:
+
+```sh
+lattices search myproject           # Find windows by content
+lattices search myproject --deep    # Include terminal tab/process data
+lattices place myproject left       # Search + focus + tile in one step
+```
+
 Claude Code skills, MCP servers, or your own scripts can drive your
 desktop the same way you do.
 
@@ -125,12 +194,15 @@ lattices                    Create or reattach to session
 lattices init               Generate .lattices.json
 lattices ls                 List active sessions
 lattices kill [name]        Kill a session
+lattices search <query>     Search windows by title, app, session, OCR
+lattices search <q> --deep  Deep search: index + terminal inspection
+lattices place <query> [pos]  Deep search + focus + tile
+lattices focus <session>    Raise a session's window
 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 scan               View current screen text
 lattices scan search <q>    Search indexed text
-lattices scan recent [n]    Browse scan history
 lattices scan deep          Trigger Vision OCR now
 lattices app                Launch the menu bar app
 lattices help               Show help
@@ -148,7 +220,11 @@ lattices help               Show help
 
 ## Docs
 
-[lattices.dev/docs](https://lattices.dev/docs/overview)
+Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview), including:
+
+- [API reference](https://lattices.dev/docs/api) — all 35 daemon methods
+- [Layers](https://lattices.dev/docs/layers) — workspace layers and tab groups
+- [Voice commands](https://lattices.dev/docs/voice) — Vox integration
 
 ## License
 

package/app/Info.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>com.arach.lattices</string>
+    <key>CFBundleName</key>
+    <string>Lattices</string>
+    <key>CFBundleDisplayName</key>
+    <string>Lattices</string>
+    <key>CFBundleExecutable</key>
+    <string>Lattices</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleVersion</key>
+    <string>0.4.1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.4.1</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>13.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+    <key>NSSupportsAutomaticTermination</key>
+    <true/>
+</dict>
+</plist>

package/app/Lattices.app/Contents/Info.plist

@@ -6,6 +6,8 @@
     <string>com.arach.lattices</string>
     <key>CFBundleName</key>
     <string>Lattices</string>
+    <key>CFBundleDisplayName</key>
+    <string>Lattices</string>
     <key>CFBundleExecutable</key>
     <string>Lattices</string>
     <key>CFBundleIconFile</key>
@@ -13,11 +15,15 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleVersion</key>
-    <string>1</string>
+    <string>0.4.1</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.1.0</string>
+    <string>0.4.1</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>13.0</string>
     <key>LSUIElement</key>
     <true/>
+    <key>NSHighResolutionCapable</key>
+    <true/>
     <key>NSSupportsAutomaticTermination</key>
     <true/>
 </dict>

package/app/Lattices.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		3sIZmtGJHMo2S/XvIMl46SOHcFY=
+		</data>
+		<key>Resources/tap.wav</key>
+		<data>
+		eOpp5td/ovQGMumXPpwy4Vyt/uc=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			LZsztS/9I1hmuQmDOk+anfxOpqVryB3y4a1kwSaUK4s=
+			</data>
+		</dict>
+		<key>Resources/tap.wav</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			K4QV08FuKEJR29hhgUbEG7Em3J6zHYpGKmGWdnZopzs=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/app/Lattices.entitlements

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- App sandbox disabled — Lattices needs direct access to tmux, processes, and the filesystem -->
+    <key>com.apple.security.app-sandbox</key>
+    <false/>
+
+    <!-- Network: localhost WebSocket daemon for CLI/agent communication -->
+    <key>com.apple.security.network.server</key>
+    <true/>
+    <key>com.apple.security.network.client</key>
+    <true/>
+</dict>
+</plist>

package/app/Package.swift

@@ -7,7 +7,14 @@ let package = Package(
     targets: [
         .executableTarget(
             name: "Lattices",
-            path: "Sources"
+            path: "Sources",
+            resources: [
+                .copy("../Resources/tap.wav"),
+            ]
+        ),
+        .testTarget(
+            name: "LatticesTests",
+            path: "Tests"
         )
     ]
 )

package/app/Sources/AdvisorLearningStore.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// Captures moments where the Claude advisor resolved something the local matcher couldn't.
+/// Each entry records the transcript, what the local system matched (or missed), and what
+/// the advisor suggested that the user accepted.
+///
+/// For now this is append-only — just growing the dataset. Future work can use it to
+/// improve local matching without needing the advisor.
+
+final class AdvisorLearningStore {
+    static let shared = AdvisorLearningStore()
+
+    struct Entry: Codable {
+        let timestamp: String
+        let transcript: String
+        let localIntent: String?
+        let localSlots: [String: String]
+        let localResultCount: Int
+        let advisorIntent: String
+        let advisorSlots: [String: String]
+        let advisorLabel: String
+    }
+
+    private let fileURL: URL
+    private let queue = DispatchQueue(label: "com.lattices.advisor-learning")
+    private static let isoFmt: ISO8601DateFormatter = {
+        let f = ISO8601DateFormatter()
+        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return f
+    }()
+
+    private init() {
+        let dir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".lattices")
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        fileURL = dir.appendingPathComponent("advisor-learning.jsonl")
+    }
+
+    /// Record that the user engaged with an advisor suggestion.
+    func record(
+        transcript: String,
+        localIntent: String?,
+        localSlots: [String: String],
+        localResultCount: Int,
+        advisorIntent: String,
+        advisorSlots: [String: String],
+        advisorLabel: String
+    ) {
+        let entry = Entry(
+            timestamp: Self.isoFmt.string(from: Date()),
+            transcript: transcript,
+            localIntent: localIntent,
+            localSlots: localSlots,
+            localResultCount: localResultCount,
+            advisorIntent: advisorIntent,
+            advisorSlots: advisorSlots,
+            advisorLabel: advisorLabel
+        )
+
+        queue.async {
+            guard let data = try? JSONEncoder().encode(entry),
+                  var line = String(data: data, encoding: .utf8) else { return }
+            line += "\n"
+
+            if let handle = try? FileHandle(forWritingTo: self.fileURL) {
+                handle.seekToEndOfFile()
+                handle.write(line.data(using: .utf8)!)
+                handle.closeFile()
+            } else {
+                try? line.data(using: .utf8)?.write(to: self.fileURL)
+            }
+
+            DiagnosticLog.shared.info("AdvisorLearning: captured [\(transcript)] → \(advisorIntent)(\(advisorSlots))")
+        }
+    }
+
+    /// Read all entries (for analysis).
+    func allEntries() -> [Entry] {
+        guard let data = try? String(contentsOf: fileURL, encoding: .utf8) else { return [] }
+        return data.components(separatedBy: "\n").compactMap { line in
+            guard !line.isEmpty, let d = line.data(using: .utf8) else { return nil }
+            return try? JSONDecoder().decode(Entry.self, from: d)
+        }
+    }
+
+    var entryCount: Int {
+        guard let data = try? String(contentsOf: fileURL, encoding: .utf8) else { return 0 }
+        return data.components(separatedBy: "\n").filter { !$0.isEmpty }.count
+    }
+}