Your windows, at your command
BetaInspect windows, arrange layouts, and make your desktop part of your scripts and AI workflows. All from the terminal.
Install the commandtangrid windows --desktop current| ID | APP |
|---|---|
| visual-studio-code1 | Visual Studio Code |
| safari1 | Safari |
tangrid mode flow
tangrid flow arrange --desktop current \
--windows visual-studio-code1,safari1 \
--style columnstangrid mode flow
tangrid flow group create \
--windows visual-studio-code1,safari1 \
--active visual-studio-code1Example IDs shown. Use the IDs returned by tangrid windows on your Mac.
Flow or Snap, Your choice
Flow keeps windows arranged. Snap arranges them once, then lets you place them yourself. Switch modes from the command line.
tangrid mode flow
tangrid flow arrange --desktop current \
--all-eligible --style columnstangrid mode snap
tangrid snap arrange --desktop current \
--all-eligible --style columnsA layout you can write down
Define splits and tab groups in JSON. Preview with --dry-run, then apply. Tangrid calculates window sizes and positions.
{
"apiVersion": 1,
"desktopId": "desktop1",
"unlisted": "error",
"layout": {
"type": "split",
"orientation": "columns",
"children": [
{ "type": "window", "windowId": "visual-studio-code1" },
{ "type": "window", "windowId": "safari1" }
]
}
}tangrid flow apply --file layout.json --dry-run
tangrid flow apply --file layout.jsonLet your AI agent arrange the desktop
A local agent with shell access can read window state, check available commands, and arrange your windows. JSON output and dry runs let it inspect and preview a change before applying it.
Install the skill
Usage example
tangrid state --json
tangrid capabilities --json
tangrid mode flow
tangrid flow balance --desktop current --jsonStart in Tangrid, Continue in Terminal
BetaOpen Tangrid
Keep the app running while you read or change window state.
Install the command
In Settings, open Window Manager → CLI and choose Install CLI.
Run your first command
Check readiness, list your windows, then explore the built-in help.
tangrid status
tangrid windows
tangrid --helpUse the bundled executable directly
With Tangrid in /Applications, run the bundled CLI or add it to PATH. Adjust the path if the app is installed elsewhere.
/Applications/Tangrid.app/Contents/CLI/tangrid --helpexport PATH="/Applications/Tangrid.app/Contents/CLI:$PATH"Add the export line to ~/.zshrc to keep it available in future terminal sessions.
Command reference
W = window, G = Flow group, D = desktop, M = display. Brackets mark optional arguments; | separates alternatives.
Common commands
| Command | Arguments | Behavior |
|---|---|---|
tangrid status | None | Read app version, mode, readiness, and busy state. |
tangrid capabilities | [--window W] | List available commands, schemas, and restrictions. |
tangrid state | [--desktop D] [--display M] | Read a snapshot of windows, displays, desktops, layout, and revision. |
tangrid windows | [--desktop D] [--display M] [--app BUNDLE_ID] [--title-contains TEXT] [--title-regex REGEX] [--placement tiled|floating|unmanaged] [--focused] | List windows matching the supplied filters. |
tangrid window W | None | Read one window's full state. |
tangrid displays | None | List displays, geometry, scale, and active desktops. |
tangrid desktops | [--display M] [--include-fullscreen] | List desktops, optionally including native fullscreen Spaces. |
tangrid mode | [flow|snap|off] | Read or change the app-wide persistent mode. |
tangrid focus W | None | Restore and focus a window, selecting its Flow tab if needed. |
tangrid focus | --from W --direction left|right|up|down | Focus a neighboring window in the specified direction. |
tangrid move W | (--display M | --desktop D) [--follow] | Move a window to a display or desktop; optionally follow it. |
tangrid resize W | --direction grow|shrink [--steps N] | Resize using the configured step and current mode's constraints. |
tangrid fill-screen W | --enabled true|false | Enable or disable Fill Screen on the existing desktop. |
tangrid fullscreen W | --enabled true|false | Enter or leave macOS native fullscreen. |
tangrid minimize W | --enabled true|false | Minimize or restore a window. |
tangrid close W | None | Request closure of a window. |
tangrid watch | [--events window,desktop,display,layout,group,mode] [--desktop D] | Subscribe to observed window, desktop, display, layout, group, or mode changes. |
tangrid operation ID | None | Inspect an accepted mutation by operation ID. |
tangrid operation | --request-id UUID | Inspect a mutation by its caller-supplied request ID. |
tangrid --help | None | Show help without requiring the app to be running. |
tangrid --version | None | Show the CLI version without requiring the app to be running. |
Flow commands
| Command | Arguments | Behavior |
|---|---|---|
tangrid flow layout | --desktop D | Read a desktop's layout relationships. |
tangrid flow tile | --windows W1,W2 | Return windows to continuous Flow management, preferring valid return points. |
tangrid flow float | --windows W1,W2 | Float the specified windows. |
tangrid flow arrange | (--windows W1,W2 [--desktop D] | --desktop D --all-eligible) --style auto|columns|rows | Gather and arrange selected windows under continuous Flow management. |
tangrid flow place | --target W_OR_G --relative-to W_OR_G --side left|right|up|down | Insert a window or group beside an existing layout region. |
tangrid flow swap | --first W_OR_G --second W_OR_G | Exchange two windows or groups on the same desktop. |
tangrid flow balance | --desktop D | Balance space distribution within window size constraints. |
tangrid flow rotate | --desktop D --direction clockwise|counterclockwise | Rotate the desktop layout. |
tangrid flow flip | --around W_OR_G | Flip the nearest enclosing split along its current orientation. |
tangrid flow orient | --around W_OR_G --orientation columns|rows | Set the nearest enclosing split to columns or rows. |
tangrid flow apply | --file FILE | --stdin | Apply a complete declarative desktop layout. |
Flow tab groups
| Command | Arguments | Behavior |
|---|---|---|
tangrid flow group list | [--desktop D] | List Flow tab groups. |
tangrid flow group get G | None | Read membership, tab order, active tab, and layout frame. |
tangrid flow group create | --windows W1,W2 [--active W1] [--anchor W1] | Create a tab group from at least two windows. |
tangrid flow group add G | --windows W3,W4 | Add the specified windows to a group. |
tangrid flow group remove G | --windows W2 [--placement tiled|floating] | Extract members, defaulting to independent tiled placement. |
tangrid flow group reorder G | --windows W2,W1,W3 | Set the complete tab order of a group. |
tangrid flow group dissolve G | [--placement tiled|floating] | Restore members to individual placement, defaulting to tiled. |
tangrid flow group move G | (--display M | --desktop D) [--follow] | Move the complete group to a display or desktop; optionally follow it. |
Snap commands
| Command | Arguments | Behavior |
|---|---|---|
tangrid snap layout | --desktop D | Read current geometry and observed snapping relationships. |
tangrid snap arrange | (--windows W1,W2 [--desktop D] | --desktop D --all-eligible) --style auto|columns|rows | Gather windows, arrange once, and enable subsequent snapping participation. |
tangrid snap place | --window W --relative-to W2 --side left|right|up|down | Split placement relative to another window. |
tangrid snap place | --window W --edge left|right | Place a window against a display edge using current geometry. |
tangrid snap set-floating | --windows W1,W2 --enabled true|false | Set exclusion from snapping while retaining current frames. |
tangrid snap apply | --file FILE | --stdin | Apply a declarative arrangement once. |
Upgrade the way you manage windows on your Mac.
Try Tangrid free for 7 days. One-time purchase, 14-day money-back guarantee.