Something went wrong. Try again.
An auto tiler for macOS
Something went wrong. Try again.
AGENTS.md #
What this is #
Parcel tiles windows on macOS 15+: Swift 6, SwiftPM, AppKit/SwiftUI, Apache-2.0. Use Swift for core, UI, scripting/tooling (parcel-dev); small shell glue.
Read CONTRIBUTING.md; real apps: Tests/Reality/README.md.
Sources/ modules; one-way dependencies in Package.swift:
ParcelCore: pure geometry, tile tree, layouts, commands,(State, Event) → (State, [Effect])reducer; no AppKit/AX/clocks/IO.ParcelConfig: TOML schema/defaults, line:column validation, keybinding grammar.CPrivateAPI: AX C header; resolve private symbols at runtime.ParcelPlatform: AX, one thread per app, window-server reads, input, permissions.ParcelAnimation: springs/curves, display-link driver, latest-wins coalescing.ParcelEngine: main-actor reactor: events/reducer/effects.ParcelIPC: Unix socket, versioned JSON.ParcelUI: menu bar, settings, onboarding, overlays.ParcelApp: composition root.prcl: CLI.FixtureApp: e2e windows.ParcelUpdate: updates.
Platform boundaries #
Use native Spaces only; never require SIP changes. Only Accessibility is required; Screen Recording is opt-in where needed.
- Run AX only on the owning app's thread; never block main on AX.
- Give every app element a 250–500 ms messaging timeout; distinguish slow, nil and dead.
- Write changed frames size → position → size; ignore events from our writes.
- Disable
AXEnhancedUserInterfaceduring writes, except with VoiceOver or Switch Control. - Debounce display changes 200–500 ms; key by UUID. Handle sleep, wake and hot-plug.
- Reconcile missing AX notifications against the window list on activity/system changes, not an idle timer.
- Version learned data (including minimum sizes); make it inspectable and resettable.
- Surface missing private APIs, bad config and lost permission to the user.
- A private call returning 0 proves nothing; read back its effect before trusting it.
Code conventions #
- Never name, quote or compare other window managers/tools anywhere in the repo, including commits/tests. Describe ideas;
Scripts/check-names.shguards names. - Borrow only MIT/BSD/Apache-2.0/Zlib code/dependencies; no GPL or source-available. Record borrowing in
NOTICE. - Load
.agents/skills/:write-swiftbefore Swift work/reviews (concurrency/testing/performance);swiftui-profor SwiftUI..claude/skills/links there. - Keep strict concurrency warning-free. Crash or surface errors; no silent
try?, force casts orAnysoup; force unwraps only in tests. - Terse, conversational docs; few comments explain why.
- Route motion through
ParcelAnimation: windows glide; chrome springs with small overshoots, never robotic/linear. Honour Reduce Motion automatically and motion-off. - Configure every product shortcut; hard-coded chords only in the defaults table.
- Make accessibility/i18n first-class: VoiceOver labels, keyboard reachability, Reduce Transparency, Increase Contrast. User strings belong in String Catalogs.
Workflow #
- Work only in assigned worktree/files; minimise/report outside edits. Raise blockers; keep scope.
mise trust && mise run setup. Commit small steps:mise exec -- git commit -s, short plain messages. No AI attribution anywhere.- Check GUI/config/CLI/IPC and reverse/recovery paths; isolate test data/processes. Report results/tests/decisions/follow-ups.
- Clean up when done; a full disk stops everyone. Each worktree build is 1–5 GB.
- Before heavy work:
df -h /. Under 20 GB free, clean first and say so. - Scratch builds go inside your worktree (
.build/<name>), never/tmp/*-build; temp dirs viamktemp -dwith atrap 'rm -rf "$work"' EXIT. - Finished: commit, then
rm -rf .build build(ormise run clean) in your worktree, delete.build/<scratch>dirs as soon as they're spent, and remove your${TMPDIR:-/tmp}leftovers (ls -dt /tmp/parcel-* /tmp/*-build). - Quit what you launched: Parcel, FixtureApp, reality driver, headless browsers,
swift test/caffeinatechildren (pgrep -fl 'Parcel|FixtureApp|swift-test|chrome-headless'). Restore VoiceOver/settings you changed; release the screen lock. - Delete test state you wrote under
~/Library/Application Support/dev.vinnymac.parcel,~/.config/parcelor defaults; prefer isolated paths so there's nothing to delete. - After merge, the owner removes the worktree and branch:
git worktree remove <path> && git branch -d <branch>, thengit worktree prune. - Report what you removed and anything you couldn't.
- Before heavy work:
Testing while iterating #
Test every change: Swift Testing (import Testing) for pure logic; window changes need a reality scenario that reads real frames back, or Tests/ParcelE2ETests driving FixtureApp. Extend fitting cases.
Format touched Swift first. Gates:
mise exec -- swift build --build-tests
mise run test && mise run lint && mise run test:scripts
make app
mise runis primary;makewraps it. Lint: strict format, safety, names, shell/workflows. Script tests: tooling and allScripts/tests/*.sh.- Unit:
mise run test, no live windows/benchmarks.swift testdiscovers all targets; e2e skips once, no launch, unlessPARCEL_E2E=1. - E2e:
Scripts/screen-lock.sh mise run e2e(ormake e2e), full target; preflight fails without grant.PARCEL_E2E_PREFLIGHT_ONLY=1: grant only. Onlybuild/Parcel.appneeds Accessibility; runner needs neither it nor Screen Recording. Quit your Parcel; harness won't control/quit it. Launch through harness; fixture windows, never yours. - Reality:
mise run realitylocks; real apps, debug-only helper inheriting Parcel's grant. Frames need no Screen Recording. All live lanes (fixture/first-light/tour too) must useScripts/screen-lock.sh.
Glossary #
Windows and geometry #
| Term | Meaning |
|---|---|
| Tile | A tile-tree leaf: one layout slot containing a stack, not necessarily one window. |
| Stack | Ordered windows sharing a tile frame, with one selected/front member; others are not automatically minimized. |
| Workspace | Parcel's layout/membership state for a display–native-Space pair; not an emulated desktop. |
| Space | A native macOS Space; desktop command numbers are not internal Space IDs. |
| Display | A UUID-identified screen with full and usable bounds. |
| Suspended display | A connected display whose placement is temporarily withheld while Space/system state is unsafe or unverified; not a disconnected screen. |
| Managed window | Retained in Parcel's management state; may be tiled or floating. |
| Floating window | Managed but excluded from the tile tree; not necessarily always on top. |
| Ignored window | Observed/classified but excluded from management; not closed. |
| Window cap | Limit on tile slots, not total windows; overflow stacks or floats. Config/CLI 0 means unlimited. |
| Layout | The strategy partitioning tile geometry; distinct from a workspace or Space. |
Product behavior #
Focus, No peek and Clean Space are independent, per-workspace modes.
| Term | Meaning |
|---|---|
| Focus | Temporarily expands/raises the selected tiled window into usable bounds minus reserved edges/outer gaps, preserving layout; not keyboard focus, fullscreen or macOS Focus. |
| No peek | Dims background around the focused window and protected auxiliaries, with optional blur; no rearrangement or Screen Recording. |
| Clean Space | Opaque backdrop concealing background clutter around protected windows; does not close windows or empty the Space. |
| Automatic tiling | Event-driven placement. The menu switch turns it off; then nothing moves on its own, but explicit commands still do. |
| Retile | Rebuild and reapply the current arrangement without changing the layout; works while Automatic tiling is off. |
Live tests and feedback #
| Term | Meaning |
|---|---|
| Reality lane | Opt-in real-app acceptance checks; verifies frames independently through the window server, not Parcel's model. |
| FixtureApp | Controllable AppKit app supplying real native test windows, including slow/clamped resize and panels; not a mock. |
| Reality driver | Socket-controlled helper embedded only in reality-enabled debug Parcel bundles; inherits its directly spawning host's Accessibility grant. |
| Screen lock | Shared filesystem mutex serializing live lanes (Scripts/screen-lock.sh); not the macOS session lock. |
| Echo | A notification attributable to Parcel's own frame write, suppressed to prevent feedback loops; not a user-origin event. |
| Readback | Observing an operation's effect after the call, not trusting its status; may establish refusal rather than success. |
| Quirk | An app/window-specific handling exception or capability, coded or learned; distinct from a user rule. |