{ "markdown": "

\n \"A\n

\n\n

Plonk

\n\n

A toolbox for your Mac, behind one menu bar icon.
\nWindows, workspaces, screenshots, OCR, a ruler, keep-awake, pointer tools,\nshortcuts, voice and agents — native, local and modular.
\nTo plonk is to set a thing down exactly where it belongs.

\n\n

\n \"Version\"\n \"macOS\n \"Swift\n \"No\n \"MIT\"\n \"MCP\"\n \"CodeQL\"\n \"OpenSSF\n

\n\n

\n ostapondo.github.io/Plonk\n

\n\n## One app instead of eight menu bar icons\n\nPlonk is a small suite of macOS tools that share one interface, one command\npalette and one automation surface. Use all of it, or switch off every module\nyou do not need.\n\n**Capture and understand the screen.** Take a region, window or full-screen\nscreenshot, annotate it, pin a live crop, copy otherwise unselectable text with\non-device OCR, or measure an interface in points and pixels.\n\n**Keep the Mac and your workflow moving.** Hold sleep off until a timer, time of\nday or process exit; find the pointer, add crosshairs or click rings; inspect the\nfront app's real shortcuts; and run anything by name from one palette.\n\n**Arrange the desk.** Draw snap zones, save workspaces that remember each\nmonitor, move windows by drag, shortcut or voice, and let app rules put new\nwindows where they belong.\n\n**Let an agent use the same tools.** Plonk ships an MCP server and CLI for\nlayouts, workspaces, screenshots, OCR, measuring, keep-awake and the rest. The\napp stays the source of truth, and the whole surface remains on your Mac.\n\n**It is early.** Version 0.4.x, one author. Shortcuts, zone files and workspaces\nare settled. The MCP tool names and the HTTP API are not, and can still change\nbetween minor versions. [CHANGELOG.md](CHANGELOG.md) says what moved.\n\n## Install\n\nmacOS 13 or newer, Apple silicon.\n\n```sh\nbrew install --cask ostapondo/plonk/plonk\n```\n\nGrant Accessibility when it asks, then relaunch. Screen Recording is asked for\nseparately, the first time you capture. Nothing else: no Full Disk Access, no\nAutomation, no Keychain.\n\nPlonk is signed but not notarized, so macOS holds a copy you download by hand.\nThe cask takes care of that for you.\n\nRunning it alongside Rectangle or Magnet is fine, as long as their shortcuts do\nnot collide.\n\n**Checking what you downloaded.** Notarizing an app means paying Apple for a\ndeveloper account, and this project does not have one, so Plonk is signed with\na certificate it made itself. That means macOS cannot tell you who built the\napp. There is a check that answers a more useful question, and you can run it\nyourself: was this exact file built by GitHub from the source in this\nrepository?\n\n```sh\ngh attestation verify Plonk-.zip --repo ostapondo/Plonk\n```\n\nPut the number from the file name in place of ``. The command comes\nwith the [GitHub CLI](https://cli.github.com), which is `brew install gh`. It\nprints the commit and the workflow run that built the archive. If the file was\naltered after it was built, or was not built from this repository at all, the\ncommand fails and tells you so.\n\nEvery release also carries a small `Plonk-.zip.sha256` file. Put it\nbeside the zip and run `shasum -a 256 -c Plonk-.zip.sha256` to confirm\nthe download arrived complete and unchanged. That file is signed the same way\nas the zip, so `gh attestation verify` works on it too. The attestation itself\nis also on the release as `Plonk-.zip.sigstore.json`, for anyone who\nwants to check it offline with `gh attestation verify --bundle` or with\n[cosign](https://github.com/sigstore/cosign) instead of asking GitHub.\n\n
\nInstalling by hand, Intel Macs, tiling managers, and removing it\n\n
\n\n**Why macOS holds a downloaded copy.** The certificate is self-signed rather\nthan an Apple Developer ID, because notarizing needs a paid Apple account and\nthis project does not have one. macOS cannot vouch for who built it, and says\nso. The cask skips that check by clearing the quarantine flag for you.\n\nThat is a check skipped on your behalf, so here is a stronger one to run before\nyou open anything:\n\n```sh\ngh attestation verify $(brew --cache)/downloads/*--Plonk-*.zip \\\n -R ostapondo/plonk\n```\n\nIt prints the commit and the GitHub Actions run that built this exact archive.\nApple's stamp would tell you a build passed a malware scan. This tells you the\nbinary came from the source in this repository, with no laptop in between.\n\n**Without Homebrew.** Download [the latest release][rel], unzip, drop Plonk.app\ninto Applications, then clear the flag yourself, which is all the cask does:\n\n```sh\nxattr -dr com.apple.quarantine /Applications/Plonk.app\n```\n\nOr do the Gatekeeper detour once: open Plonk, dismiss the warning, then System\nSettings, Privacy & Security, scroll to Security, **Open Anyway**.\n\n**If you move or rename Plonk.app** later, macOS ties the old grant to the old\npath and windows of newly launched apps stop being seen. Remove Plonk from\nPrivacy & Security, Accessibility, and grant it again.\n\n**On an Intel Mac.** Releases are built for Apple silicon only, so the download\nwill not run. Building from source ought to work, see [Build](#build), but\nnobody has tried it and a report either way is welcome in [issues][hw].\n\n**Next to a tiling manager.** yabai and Amethyst own every window on screen and\nwill pull windows straight back out of a zone. Run one or the other.\n\n**Removing it.** `brew uninstall --cask plonk`, or quit Plonk and drag it to the\ntrash. Then delete `~/Library/Application Support/Plonk/`. The login item goes\nwith the app, and nothing was written anywhere else.\n\n
\n\n## The tools\n\nThe modules share settings, shortcuts, the menu bar, the command palette and the\nsame local API. Turning one off removes its page, menu items, shortcuts, manager\nand agent routes while keeping its settings for later.\n\n| | |\n| --- | --- |\n| **Screenshots and annotation** | Capture a region, window or full screen at native resolution, then add pen strokes, arrows, shapes or highlights before saving |\n| **On-device OCR** | `⌃⌥T` copies words from a screenshot, paused video, dialog or locked PDF without uploading a pixel |\n| **Screen ruler** | `⌃⌥R` reads clearances and dragged distances in both macOS points and physical pixels |\n| **Live crops** | Pin a changing part of the screen above everything else. It streams live and is never written to disk |\n| **Pulse** | Keep the Mac awake by timer, schedule, open app, charging state or process lifetime. It uses real power assertions and hands sleep back when the session ends |\n| **Pointer tools** | Find the cursor, add configurable crosshairs or click rings, and jump the pointer to the next display |\n| **Shortcut guide** | Read every shortcut the front app actually exposes through its menus instead of relying on a stale cheat sheet |\n| **[Zones and workspaces](docs/zones.md)** | Draw window places, save apps and documents as a desk, and return everything to the correct displays. [Workspace details](docs/workspaces.md) |\n| **Voice, CLI and agents** | Run the same tools by name, from speech, the `plonk` command or twenty-two MCP tools. Recognition for common voice commands stays on-device |\n\nAll but the shortcut guide can be switched off, from Tools in the menu bar\ndropdown or the Tools page. Off means gone: out of the sidebar, out of the\nmenu, its shortcuts released, and its tools refused to agents until it is back\non. The same switches cover zones, workspaces and voice, so desk arrangement\ncan stand down while the rest of Plonk keeps running.\n\nIf you are coming from Rectangle, Magnet, Loop or Raycast, the familiar window\nshortcuts can come with you. One button imports Rectangle bindings and existing\n`rectangle://` scripts need one substitution. [Coming from Rectangle](docs/from-rectangle.md)\nhas the details.\n\nLonger versions: [Zones](docs/zones.md) · [Workspaces](docs/workspaces.md) ·\n[Hotkeys](docs/hotkeys.md) · [Everything else](docs/features.md) ·\n[Coming from Rectangle](docs/from-rectangle.md)\n\n## For agents\n\nAn agent gets the same toolbox as the menu bar: capture or read the screen,\nmeasure an interface, control an awake session, inspect the desk, arrange it and\nsave the result.\n\n```\nkeep the Mac awake until this build finishes\nread the error out of that dialog and tell me what it says\nhow tall is that toolbar, in points and in pixels\ncapture this window and highlight the warning\nput the browser on the left, then save this desk as \"review\"\n```\n\nTwenty-two tools cover state, capture, OCR, measuring, keep-awake, layouts,\nworkspaces and zones. Several agents can connect at once, each registering\nitself, with an optional mode that locks changes to the active one.\n\nSetup, if you want the `plonk` CLI or an agent driving it (Node 18+):\n\n```sh\nclaude mcp add plonk -- npx -y plonk-mcp # Claude Code\ncodex mcp add plonk -- npx -y plonk-mcp # Codex CLI\n```\n\nIn Claude Code it can also be a plugin: same server, pinned to the release it\nshipped with rather than to whatever npm serves as latest.\n\n```\n/plugin marketplace add ostapondo/plonk\n/plugin install plonk@plonk\n```\n\nFor Claude Desktop there is nothing to type. Download `plonk-.mcpb`\nfrom the [latest release][rel] and open it. The bundle carries the server and\nits dependencies, so no config file is edited and nothing is fetched at launch.\n\nAny MCP client works, over stdio or HTTP. One-pagers for\n[Cursor](docs/clients/cursor.md), [Zed](docs/clients/zed.md) and\n[Cline](docs/clients/cline.md).\n\nThe same package carries a `plonk` command, for the things that are neither an\nagent nor a settings window:\n\n```sh\nplonk state # screens, zone sets, workspaces, windows\nplonk launch review # a saved workspace\nplonk awake while npm run build # awake for exactly as long as the build\nplonk text | pbcopy # OCR a region into the clipboard\nplonk measure 0.5 0.5 # size of what is mid-screen, in points and pixels\n```\n\n**[For agents](docs/agents.md)** has every tool, the multi-agent rules, the HTTP\ntransport and the rest of the CLI.\n\n## Privacy\n\nNo account, no cloud, no telemetry. The API binds to `127.0.0.1`, refuses\nanything carrying headers a browser cannot suppress, and is gated on a token\nonly you can read. The one outbound connection is the update check, which\ncarries no identifier and can be switched off.\n\nNone of that is a claim you have to take on trust. Releases are built and signed\non GitHub's runners and ship with an attestation, so the binary on your Mac ties\nback to the commit it came from:\n\n```sh\ngh attestation verify Plonk-.zip -R ostapondo/plonk\n```\n\n**[Check it yourself](docs/verify.md)** is every claim above with the command\nthat tests it. [SECURITY.md](SECURITY.md) says where each promise stops.\n\n## Under the hood\n\n

\n \"Claude\n

\n\n- The app is the single source of truth. The MCP server is a stateless bridge.\n- `App/` is the Swift menu bar app, `mcp/` the TypeScript MCP server.\n- Config is plain JSON at `~/Library/Application Support/Plonk/config.json`.\n\n## Build\n\nSeven commands, and they are what CI runs on every pull request. Each line is a\nsubshell, so paste the block from the repository root.\n\n```sh\n(cd App && swift build) # the app compiles\n./scripts/test.sh # the unit suite\n./scripts/lint.sh # style rules, no dependencies\n(cd mcp && npm ci && npm test) # the MCP server\nnode scripts/check-zone-sets.mjs # the layouts in zone-sets/\nnode scripts/check-strings.mjs # every word the user reads\n./scripts/check-security-claims.sh # what SECURITY.md promises\n```\n\nNone of that needs a signing certificate. Zone geometry, config decoding, HTTP\nrouting, MCP tools, voice parsing, the CLI and every document here are reachable\nfrom that loop, and most changes need nothing more.\n\nProducing a launchable `Plonk.app` does need one. Make your own once with\n`./scripts/make-signing-cert.sh`, then run `./scripts/build.sh`. macOS ties\nAccessibility and Screen Recording to the code signature, and an ad-hoc one\nchanges every build, so a stable certificate is what stops rebuilds from\nresetting permissions.\n\n## Contributing\n\nBug reports, zone sets, client one-pagers and code are all welcome. None of them\nneed a signing certificate.\n\n- **The smallest useful change is one JSON file.** [`zone-sets/`](zone-sets/) is\n a gallery of layouts worth copying: an ultrawide split, a rotated monitor, the\n one built around a recurring meeting. Draw it in the app, read the numbers out\n of `plonk state --json`, open a pull request. That folder has its own CI job\n and answers in about twenty seconds. No build, no signing, no Swift.\n- **[good first issue][gfi]** issues are written to be picked up cold. Each says\n where the code is and how to tell it worked, and carries a prompt you can hand\n to an agent, since [AGENTS.md](AGENTS.md) already explains the repo to one.\n- **[needs-hardware][hw]** is where a request for a desk nobody here has gets\n tagged, and answering one needs neither Swift nor a certificate. Desk tools\n meet hardware the author cannot see, so a report from three monitors or an\n ultrawide is worth more than a patch. An empty list is not a filled gap: open\n an issue with the arrangement you have and what happened.\n\n[CONTRIBUTING.md](CONTRIBUTING.md) has the rest, including how long a review\ntakes. Questions and half-formed ideas go to\n[Discussions](https://github.com/ostapondo/plonk/discussions). A security\nproblem goes through [SECURITY.md](SECURITY.md), not a public issue. Everyone\ntaking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n[gfi]: https://github.com/ostapondo/plonk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22\n[hw]: https://github.com/ostapondo/plonk/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds-hardware\n[rel]: https://github.com/ostapondo/plonk/releases/latest\n\n## License\n\nMIT © [ostapondo](https://github.com/ostapondo)\n", "bytes": 15245, "sha": "a9d067fdc443b3dc1277a11585ab4f830158920df7a5591dfbab93ebc209d012", "repo_slug": "ostapondo/plonk", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ostapondo_plonk_63f5b54c/readme" }