Your windows, at your command

Beta

Inspect windows, arrange layouts, and make your desktop part of your scripts and AI workflows. All from the terminal.

Install the command
tangrid mode flow
tangrid flow arrange --desktop current \
  --windows visual-studio-code1,safari1 \
  --style columns

Example 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.

FlowContinuous automatic layout
tangrid mode flow
tangrid flow arrange --desktop current \
  --all-eligible --style columns
SnapArrange once, then place freely
tangrid mode snap
tangrid snap arrange --desktop current \
  --all-eligible --style columns

A 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.json

Let 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

Install the Tangrid skill from https://tangrid.app/SKILL.md
SKILL.mdCopied

Usage example

Balance the windows on my current desktop.
tangrid state --json
tangrid capabilities --json
tangrid mode flow
tangrid flow balance --desktop current --json

Start in Tangrid, Continue in Terminal

Beta
  1. Open Tangrid

    Keep the app running while you read or change window state.

  2. Install the command

    In Settings, open Window Manager → CLI and choose Install CLI.

  3. Run your first command

    Check readiness, list your windows, then explore the built-in help.

tangrid status
tangrid windows
tangrid --help
Use 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 --help
export 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

CommandArgumentsBehavior
tangrid statusNoneRead 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 WNoneRead one window's full state.
tangrid displaysNoneList 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 WNoneRestore and focus a window, selecting its Flow tab if needed.
tangrid focus--from W --direction left|right|up|downFocus 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|falseEnable or disable Fill Screen on the existing desktop.
tangrid fullscreen W--enabled true|falseEnter or leave macOS native fullscreen.
tangrid minimize W--enabled true|falseMinimize or restore a window.
tangrid close WNoneRequest 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 IDNoneInspect an accepted mutation by operation ID.
tangrid operation--request-id UUIDInspect a mutation by its caller-supplied request ID.
tangrid --helpNoneShow help without requiring the app to be running.
tangrid --versionNoneShow the CLI version without requiring the app to be running.

Flow commands

CommandArgumentsBehavior
tangrid flow layout--desktop DRead a desktop's layout relationships.
tangrid flow tile--windows W1,W2Return windows to continuous Flow management, preferring valid return points.
tangrid flow float--windows W1,W2Float the specified windows.
tangrid flow arrange(--windows W1,W2 [--desktop D] | --desktop D --all-eligible) --style auto|columns|rowsGather and arrange selected windows under continuous Flow management.
tangrid flow place--target W_OR_G --relative-to W_OR_G --side left|right|up|downInsert a window or group beside an existing layout region.
tangrid flow swap--first W_OR_G --second W_OR_GExchange two windows or groups on the same desktop.
tangrid flow balance--desktop DBalance space distribution within window size constraints.
tangrid flow rotate--desktop D --direction clockwise|counterclockwiseRotate the desktop layout.
tangrid flow flip--around W_OR_GFlip the nearest enclosing split along its current orientation.
tangrid flow orient--around W_OR_G --orientation columns|rowsSet the nearest enclosing split to columns or rows.
tangrid flow apply--file FILE | --stdinApply a complete declarative desktop layout.

Flow tab groups

CommandArgumentsBehavior
tangrid flow group list[--desktop D]List Flow tab groups.
tangrid flow group get GNoneRead 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,W4Add 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,W3Set 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

CommandArgumentsBehavior
tangrid snap layout--desktop DRead current geometry and observed snapping relationships.
tangrid snap arrange(--windows W1,W2 [--desktop D] | --desktop D --all-eligible) --style auto|columns|rowsGather windows, arrange once, and enable subsequent snapping participation.
tangrid snap place--window W --relative-to W2 --side left|right|up|downSplit placement relative to another window.
tangrid snap place--window W --edge left|rightPlace a window against a display edge using current geometry.
tangrid snap set-floating--windows W1,W2 --enabled true|falseSet exclusion from snapping while retaining current frames.
tangrid snap apply--file FILE | --stdinApply 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.