An auto tiler for macOS
parcel docs configuration.md
11 kB · 225 lines
Markdown
at main

Configuration #

Settings and ~/.config/parcel/parcel.toml share the same preferences. On first launch, Parcel creates the file with an editor schema hint; existing files are left alone. Omitted values use defaults.

Setup uses your current configuration, not a separate tour preset. Manual means Automatic tiling is off; layouts, rules, mouse controls, and configured shortcuts still work. Retile explicitly arranges windows while it is off. Adjust layouts, tile counts, gaps, and reserved edges in Settings → Layout; edit rules in Settings → Rules, and motion in Settings → Motion.

#:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json
version = 1

[general]
prefix = "ctrl-alt"

[layout]
default = "grid"
portrait-layout = "rows"
window-cap = 3
when-full = "stack"
gaps = { inner = 8, outer = 8 }

[motion]
enabled = true
transitions = "glide"

[keybindings]
focus-left = "hyper-h"
stack = false

Edits reload automatically. Invalid edits report a line and column and keep the last good configuration. Unknown keys warn; wrong types, ranges, versions, and conflicting shortcuts reject the edit. Setting names use dashes, not underscores.

Layouts and tile counts #

Layouts are grid, columns, rows, side, tree, bsp, and accordion. portrait-layout defaults to rows on displays taller than they are wide; landscape and square displays use default. Display overrides use UUIDs and inherit omitted values, including individual gaps and reserved edges.

ratio sets the main tile's share when the second tile arrives and accepts values from 0.1 to 0.9. Settings offers Half, 60%, and Two thirds presets for every layout except Accordion. Later window arrivals can split an existing tile.

The default cap is three tiles. window-cap accepts whole numbers from 0 through 100. Positive requests are limited by the layout’s adaptive display capability without changing the stored request. 0 explicitly opts out of both limits. Settings and the menu show the requested and effective counts.

At the effective cap, new windows join the active tile. Set when-full = "float" to center them instead. Overflow windows stay floating until you tile them or a rule does; title changes and reloads leave them where you put them. Lowering the effective cap merges the last tiles into the previous tile.

set-window-cap 1 through set-window-cap 5 are configurable count presets. set-window-cap 0 removes the limit and is unbound by default. Reloads preserve custom splits and runtime ratio/cap choices when those config values haven’t changed. See the module guide for per-display overrides, tree editing, focus modes, and named binding modes.

Shortcuts and motion #

hyper means Control–Option–Command–Shift. general.prefix changes default bindings except Tab View, Settings, and Quit; explicit chords are absolute. Use false to unbind a command. Keys are physical ANSI keys, so their positions do not follow the input language. Settings → Shortcuts shows the resolved bindings and flags conflicts. An explicit binding that matches another command’s inherited default is a conflict; disable or rebind that default as well.

The default prefix is Control–Option (⌃⌥). These are the complete default bindings:

Action Shortcut
Swap left / right / up / down ⌃⌥← / ⌃⌥→ / ⌃⌥↑ / ⌃⌥↓
Focus left / right / up / down ⌃⌥⇧← / ⌃⌥⇧→ / ⌃⌥⇧↑ / ⌃⌥⇧↓
Move left / right / up / down ⌃⌥⇧A / ⌃⌥⇧D / ⌃⌥⇧W / ⌃⌥⇧S
Make primary ⌃⌥Return
Window controls ⌃⌥\
Next / previous window ⌃⌥] / ⌃⌥[
Stack / unstack ⌃⌥Space / ⌃⌥;
Next / previous stack member ⌃⌥</kbd> / ⌃⌥⇧<kbd>
Grow / shrink / reset sizes ⌃⌥= / ⌃⌥− / ⌃⌥0
Float / tile; always float ⌃⌥F / ⌃⌥⇧F
Focus / No Peek / Clean Space ⌃⌥Z / ⌃⌥D / ⌃⌥P
Automatic tiling ⌃⌥T
Retile ⌃⌥R
Grid / Columns / Rows / Side / Tree / BSP / Accordion ⌃⌥G / ⌃⌥C / ⌃⌥Y / ⌃⌥E / ⌃⌥⇧T / ⌃⌥B / ⌃⌥O
Horizontal / vertical split ⌃⌥X / ⌃⌥V
Join left / right / up / down ⌃⌥F5 / ⌃⌥F6 / ⌃⌥F7 / ⌃⌥F8
Balance / rotate / mirror horizontally / vertically ⌃⌥F9 / ⌃⌥F10 / ⌃⌥F11 / ⌃⌥F12
Window cap 1 / 2 / 3 / 4 / 5 ⌃⌥⌘1 / ⌃⌥⌘2 / ⌃⌥⌘3 / ⌃⌥⌘4 / ⌃⌥⌘5
Snap left / right / top / bottom half ⌃⌥6 / ⌃⌥7 / ⌃⌥8 / ⌃⌥9
Undo / undo last rule ⌃⌥U / ⌃⌥F17
Close / fullscreen / hover focus ⌃⌥Delete / ⌃⌥M / ⌃⌥I
Move to display left / right / up / down ⌃⌥⌘F1 / ⌃⌥⌘F2 / ⌃⌥⌘F3 / ⌃⌥⌘F4
Tab View ⌥Tab
Settings / Quit ⌘, / ⌘Q

Tab View works independently of the prefix. Rebind or disable it with tab-view in [keybindings]. While it is open, Tab and Shift–Tab cycle, arrows move between cards, Return or a click selects, and Escape cancels. Floating and minimized windows appear in separate rows below the tiles. Ignored windows never appear, even when minimized. Dense layouts use a scrollable grid instead of shrinking cards below 180 × 64 points; every card keeps an icon and a truncated title. Keyboard selection scrolls its card into view.

Releasing an opening modifier selects; Shift remains available for navigation when another modifier is held. A shortcut without modifiers stays open until Return, a click, or Escape. With VoiceOver enabled, the panel takes keyboard focus and stays open after modifier release. VoiceOver chords, Caps Lock input, and Quick Nav arrows are routed to that panel, not the background app. Use Return, a click, or Escape to finish. Escape returns to the previously focused app.

A minimized tiled window returns to its saved tile if that placement is still valid. Otherwise it joins the focused workspace's next layout slot and explains that the layout changed. A queued restore is tied to the original window generation, so a recycled window ID cannot restore a replacement window.

If the prefix includes Shift, focus uses H/L/K/J, move right uses F13, previous stack member uses backslash, always float uses F16, and Tree uses F18. Window controls uses F19. Other keys remain the same. Explicit bindings keep their exact modifiers. At a display edge, swap moves to the next display in that direction. If it is full, the destination workspace's when-full = "stack" joins the neighboring tile. Otherwise general.when-display-full = "stack" also stacks; "swap" exchanges windows. To exchange across a full display, choose when-full = "float" for that display and when-display-full = "swap". Explicit display moves and new windows keep their existing overflow behavior.

Control–Option is also VoiceOver’s default modifier. Several chords overlap VoiceOver commands, including arrows, Return, brackets, Space, and Control–Option–Command–1 through 5. Control–Option–Space can also select the next input source. VoiceOver or macOS may intercept these; choose a different prefix or rebind them. Conflict checks use enabled system shortcuts and the current app’s menus, and do not catalog all VoiceOver commands.

Mouse gestures use their own modifier settings, separate from the keyboard prefix.

Motion #

[motion]
enabled = true
speed = 1
level = "playful"
transitions = "glide"
  • enabled controls motion globally and defaults to true. Reduce Motion takes precedence: windows move instantly and overlays use a brief fade where needed.
  • speed is a multiplier: 1 is normal, smaller numbers are slower, and larger numbers are faster. Settings offers steps of 0.6, 0.8, 1, 1.4, and 2; the TOML file accepts any number from 0.1 through 4 inclusive.
  • level controls motion character, not speed. calm removes bounce and moves windows instantly; playful is the default; extra adds bounce to some effects.
  • transitions controls window movement: glide animates windows; ghost moves them instantly with an animated outline; snap moves them instantly without the outline. glide is the default.

Feedback sounds are opt-in via motion.sound and are suppressed with Reduce Motion.

Appearance #

system keeps native macOS colors. Six palettes are available: kiln (Parcel’s house terracotta, ochre, and teal), tide, grove, iris, dusk, and rose. mode is system, light, or dark and affects Parcel’s windows and chrome, not other apps. Changes apply instantly without moving windows or changing layout.

[appearance]
palette = "kiln"
mode = "system"
border-opacity = 1.0
border-radius = 10.0
active-border-color = "#B65C44"

border-opacity accepts 0–1 (default 1); border-radius accepts 0–40 points. Omit border-radius to match each window’s native corner radius. Every explicit value, including 10, uses that radius. Optional overrides use exactly #RRGGBB: active-border-color, inactive-border-color, glow-color, chip-background-color, chip-text-color, stack-accent-color, and clean-space-backdrop-color. Omitted roles use the palette. With system, focus-modes.clean-space-color keeps its graphite, mist, or stone backdrop, including under Increase Contrast. Named palettes and explicit backdrop overrides control that color instead; the Focus modes picker explains when it is disabled. Settings lists custom overrides and can reset one role or all of them. Palette preview cards select a palette and summarize both modes for VoiceOver.

Custom colors and reduced border opacity are not guaranteed to meet WCAG contrast requirements. Accessibility preferences, including Increase Contrast and Reduce Transparency, take priority and keep borders fully opaque.

No Peek dimming #

The menu’s dimming slider and Settings → Focus modes share the global focus-modes.no-peek-level preference. It accepts 0.1 through 0.9 and controls the dimming wherever No Peek is enabled. The default is 0.25, with blur enabled: gentler dimming keeps neighboring window shapes visible while blur obscures their text. Existing explicit levels are kept.

Editor support #

Editors that support TOML schema hints can use the published schema. The schema checks structure; Parcel also checks shortcut conflicts and native expression syntax. To regenerate it without a running app:

mise exec -- swift run prcl schema > docs/parcel.schema.json

A test compares the published file byte-for-byte with the exporter. Parser, validation, editing, and hot-reload APIs are in the ParcelConfig guide.

For more choices, see window rules, callbacks, and layout memory.