Plonk

<p align="center">
  <img src="docs/banner.gif" width="640"
       alt="The Plonk cube drops a window into the second of four gradient-filled zones, which frames it with a visible gap">
</p>

<h1 align="center">Plonk</h1>

<p align="center"><strong>Give every window a place to live. Draw the boxes you
actually want, then drop windows into them — with a drag, a key, or by saying so
out loud.</strong><br>
<sub>To plonk is to set a thing down exactly where it belongs.</sub></p>

<p align="center">
  <img alt="Version" src="https://img.shields.io/github/v/release/ostapondo/Plonk?style=flat-square&color=8b5cf6&label=version">
  <img alt="macOS 13+" src="https://img.shields.io/badge/macOS-13%2B-3a6bff?style=flat-square">
  <img alt="Swift 6" src="https://img.shields.io/badge/Swift-6-ff4f81?style=flat-square">
  <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-12d3a4?style=flat-square">
  <img alt="MIT" src="https://img.shields.io/badge/license-MIT-ffc531?style=flat-square">
  <img alt="MCP" src="https://img.shields.io/badge/MCP-20_tools-8b5cf6?style=flat-square">
  <img alt="CodeQL" src="https://img.shields.io/github/actions/workflow/status/ostapondo/Plonk/codeql.yml?style=flat-square&label=CodeQL">
  <img alt="OpenSSF Scorecard" src="https://img.shields.io/ossf-scorecard/github.com/ostapondo/Plonk?style=flat-square&label=OpenSSF%20Scorecard">
</p>

<p align="center">
  <a href="https://ostapondo.github.io/Plonk/"><strong>ostapondo.github.io/Plonk</strong></a>
</p>

## Why another one

You most likely already have Rectangle, Magnet, Loop or Raycast. If a fixed grid
of halves and thirds is all you want, they do it well. Plonk is for three things
they do not do.

Coming from one of them costs nothing: the ten placement shortcuts are the same
keys, one button takes the rest, and an existing `rectangle://` script is one
substitution away. [Coming from Rectangle](docs/from-rectangle.md) is the whole
of it.

**Zones you draw.** Not a preset grid. Any number of zones, any size, a
different set per monitor, overlapping if that suits you. Click a zone to split
it, `⇧`-click to split the other way: a narrow rail for chat, a wide middle
split in two, a strip for the terminal.

**Workspaces that remember which monitor.** Save the desk: the apps, every
window's frame, and the display each one belongs on. Launch it onto an empty
desktop and it rebuilds itself, on the right screens.

**An agent can drive all of it.** Plonk ships an MCP server that covers its
whole surface: layouts, workspaces, zones, keep-awake, screenshots, on-device
OCR, measuring. Generic macOS automation servers can nudge a window around. This
is the window manager itself, so "browser on the left 60%, terminal top right,
save that as a workspace called review" is one sentence rather than a script.

The other seven tools, OCR and a ruler and keep-awake among them, are there
because each was otherwise its own icon in the menu bar.

**It is early.** Version 0.2.x, one author. Shortcuts, zone files and workspaces
are settled. The MCP tool names and the HTTP API are not, and can still change
between minor versions. [CHANGELOG.md](CHANGELOG.md) says what moved.

## Three ways to move a window

<p align="center">
  <img src="docs/ways.svg" width="720"
       alt="Four cards, one per way to move a window: drag it and the zones light up, hold ⌘ for two at once; ⌃⌥1 to ⌃⌥9 for the numbered zones with ⌃⌥0 as the oops key; ⌃⌥V to say it, offline and on-device; or ask an agent, through twenty MCP tools">
</p>

**Drag it.** Zones light up as you move a window, and it drops into one. Hold
`⌘` too and it takes two of them at once. Turn on grab-and-move to pull a window
from anywhere inside it instead of aiming for the title bar.

**Press a key.** `⌃⌥←` for the left half. `⌃⌥1` to `⌃⌥9` for the numbered zones
on that screen. `⌃⌥0` puts a window back where it was before Plonk touched it.

**Say it.** Hold `⌃⌥V` and name the place: "snap this left", "zone three". That
runs in the app, offline, on-device.

Five zone sets ship with it, and past those you draw your own. Swap the set on a
screen and any window already in a numbered zone moves to wherever that number
is now.

<p align="center">
  <img src="docs/zone-swap.svg" width="720"
       alt="The same screen under two zone sets. In the first, zone 1 is a narrow left rail, zone 2 the wide middle, zone 3 the right column; after ⌃⌥⇧2 the shape is different but the numbers are not, so the window in zone 2 is still in zone 2">
</p>

Colour is the zone number, everywhere it is drawn: 1 rose, 2 plum, 3 blue,
4 mint, 5 sun, 6 sky. In the overlay you drag into, in the editor, in the menu
bar, and in every picture on this page. A set can be read before a digit is.

## Install

macOS 13 or newer, Apple silicon.

```sh
brew install --cask ostapondo/plonk/plonk
```

Grant Accessibility when it asks, then relaunch. Screen Recording is asked for
separately, the first time you capture. Nothing else: no Full Disk Access, no
Automation, no Keychain.

Plonk is signed but not notarized, so macOS holds a copy you download by hand.
The cask takes care of that for you.

Running it alongside Rectangle or Magnet is fine, as long as their shortcuts do
not collide.

**Checking what you downloaded.** Notarizing an app means paying Apple for a
developer account, and this project does not have one, so Plonk is signed with
a certificate it made itself. That means macOS cannot tell you who built the
app. There is a check that answers a more useful question, and you can run it
yourself: was this exact file built by GitHub from the source in this
repository?

```sh
gh attestation verify Plonk-<version>.zip --repo ostapondo/Plonk
```

Put the number from the file name in place of `<version>`. The command comes
with the [GitHub CLI](https://cli.github.com), which is `brew install gh`. It
prints the commit and the workflow run that built the archive. If the file was
altered after it was built, or was not built from this repository at all, the
command fails and tells you so.

Every release also carries a small `Plonk-<version>.zip.sha256` file. Put it
beside the zip and run `shasum -a 256 -c Plonk-<version>.zip.sha256` to confirm
the download arrived complete and unchanged. That file is signed the same way
as the zip, so `gh attestation verify` works on it too. The attestation itself
is also on the release as `Plonk-<version>.zip.sigstore.json`, for anyone who
wants to check it offline with `gh attestation verify --bundle` or with
[cosign](https://github.com/sigstore/cosign) instead of asking GitHub.

<details>
<summary>Installing by hand, Intel Macs, tiling managers, and removing it</summary>

<br>

**Why macOS holds a downloaded copy.** The certificate is self-signed rather
than an Apple Developer ID, because notarizing needs a paid Apple account and
this project does not have one. macOS cannot vouch for who built it, and says
so. The cask skips that check by clearing the quarantine flag for you.

That is a check skipped on your behalf, so here is a stronger one to run before
you open anything:

```sh
gh attestation verify $(brew --cache)/downloads/*--Plonk-*.zip \
  -R ostapondo/plonk
```

It prints the commit and the GitHub Actions run that built this exact archive.
Apple's stamp would tell you a build passed a malware scan. This tells you the
binary came from the source in this repository, with no laptop in between.

**Without Homebrew.** Download [the latest release][rel], unzip, drop Plonk.app
into Applications, then clear the flag yourself, which is all the cask does:

```sh
xattr -dr com.apple.quarantine /Applications/Plonk.app
```

Or do the Gatekeeper detour once: open Plonk, dismiss the warning, then System
Settings, Privacy & Security, scroll to Security, **Open Anyway**.

**If you move or rename Plonk.app** later, macOS ties the old grant to the old
path and windows of newly launched apps stop being seen. Remove Plonk from
Privacy & Security, Accessibility, and grant it again.

**On an Intel Mac.** Releases are built for Apple silicon only, so the download
will not run. Building from source ought to work, see [Build](#build), but
nobody has tried it and a report either way is welcome in [issues][hw].

**Next to a tiling manager.** yabai and Amethyst own every window on screen and
will pull windows straight back out of a zone. Run one or the other.

**Removing it.** `brew uninstall --cask plonk`, or quit Plonk and drag it to the
trash. Then delete `~/Library/Application Support/Plonk/`. The login item goes
with the app, and nothing was written anywhere else.

</details>

## What you get

The window manager is four things, and this is the part of each that the
sections above left out.

| | |
| --- | --- |
| **[Zones](docs/zones.md)** | Overlap them, gap them, hide the numbers, keep a list of apps Plonk never touches. Windows return to their zone after a display is unplugged and plugged back in |
| **[Workspaces](docs/workspaces.md)** | Files, folders or URLs each app should open on the way up, so a desk comes back with the right documents and not just the right apps. Monitors are keyed by UUID, so unplugging one does not scramble them |
| **Focus that follows the layout** | `⌃⌥⇧←` goes to the window actually on the left, not the one you used last. `` ⌃⌥` `` cycles the windows stacked in one zone |
| **Voice** | Hold `⌃⌥V` and say it. Common commands run in the app, offline. Anything bigger goes to your agent. Recognition is on-device |

And the [MCP server](#for-agents), which is every one of these as a tool an
agent can call.

<details>
<summary>Seven smaller things, behind the same menu bar icon</summary>

<br>

| | |
| --- | --- |
| **Text off the screen** | `⌃⌥T` selects an area and copies the words in it: a screenshot, a paused video, a dialog that will not let you select. On-device |
| **A ruler** | `⌃⌥R`, then hover: how far the pointer can go each way before it meets an edge, read off the pixels. The width of a row,