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"
enabledcontrols motion globally and defaults totrue. Reduce Motion takes precedence: windows move instantly and overlays use a brief fade where needed.speedis a multiplier:1is normal, smaller numbers are slower, and larger numbers are faster. Settings offers steps of0.6,0.8,1,1.4, and2; the TOML file accepts any number from0.1through4inclusive.levelcontrols motion character, not speed.calmremoves bounce and moves windows instantly;playfulis the default;extraadds bounce to some effects.transitionscontrols window movement:glideanimates windows;ghostmoves them instantly with an animated outline;snapmoves them instantly without the outline.glideis 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.