Skip to content
Back to search

ploink

Hold one button, ship the fix. A deploy console for your Mac, with an MCP server so coding agents can deploy with your permission.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/petarjs--ploink/badge.svg)](/listings/petarjs--ploink)

HTML

<a href="/listings/petarjs--ploink"><img src="/api/listings/petarjs--ploink/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Beta download (unsigned):** get the latest `Ploink.dmg` from [Releases](https://github.com/petarjs/ploink/releases), drag Ploink to Applications, then right-click it and choose **Open** the first time. macOS shows a warning because the beta isn't signed yet. The signed, notarized build goes to founding members first.

**From source:**

npm install
npm start

To get a real app you can put in `/Applications`:

npm run dist
open dist/mac-arm64

Drag `Ploink.app` to Applications. It is not code-signed, which is fine for an app you built yourself on this Mac.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 313 lines
  1. <p align="center"><img src="docs/cover.jpg" alt="Ploink: hold one button, ship the fix" width="820"></p>
  2. # Ploink
  3. **Hold one button. Ship the fix.**
  4. [ploink.dev](https://ploink.dev) · [Founding pre-order](https://vizzmo.gumroad.com/l/ploink) · MIT licensed · macOS (Apple Silicon)
  5. A deploy console for your Mac. Each project gets a big, physical-feeling button.
  6. Hold it, the LED ring charges, it fires, and the VFD readout streams the deploy.
  7. Press F5 anywhere and a launch bar of mini buttons slides in from a screen edge,
  8. or grows out of the notch. Coding agents can press the buttons too, through a
  9. built-in MCP server.
  10. No CI minutes, no runners, no cloud. Your deploy commands run on your machine,
  11. in your login shell, exactly like you would run them by hand.
  12. <p align="center"><img src="docs/demo.gif" alt="Ploink demo: an agent asks to deploy, you hold the button, it ships" width="720"></p>
  13. ## Install
  14. **Beta download (unsigned):** get the latest `Ploink.dmg` from
  15. [Releases](https://github.com/petarjs/ploink/releases), drag Ploink to Applications,
  16. then right-click it and choose **Open** the first time. macOS shows a warning because
  17. the beta isn't signed yet. The signed, notarized build goes to founding members first.
  18. **From source:**
  19. ```bash
  20. npm install
  21. npm start
  22. ```
  23. To get a real app you can put in `/Applications`:
  24. ```bash
  25. npm run dist
  26. open dist/mac-arm64
  27. ```
  28. Drag `Ploink.app` to Applications. It is not code-signed, which is fine for an
  29. app you built yourself on this Mac.
  30. ## Using it
  31. | Do this | To |
  32. | --- | --- |
  33. | Drop a project folder on the window, or click **+** | Add a project. Ploink reads `package.json`, picks the deploy scripts, the package manager, the site URL and the icon. |
  34. | **Press and hold** a button | Deploy. Let go early to cancel. |
  35. | Hold **1–9** | Deploy bay 1–9 from the keyboard. |
  36. | **F5** (anywhere) | Slide the launch bar in or out (or open the console, if you prefer). Change it in Settings. |
  37. | Click the readout (or the ≡ icon) | Open the log drawer with the deploy history. |
  38. | Right-click a bay (or the ⋯ icon) | Edit name, folder, website, commands, cap colour, approval. |
  39. | The selector switch under a button | Pick which command the button fires (for example prod / preview). |
  40. | Click a small key under the button | Run an action key: a health check, `git pull`, tests, or start and stop the dev server. Keys marked "hold to run" need a long press. |
  41. What happens when you deploy:
  42. 1. **Ignition.** The cap slams down, a pressure ring and a puff of smoke, and an
  43. unresolved chord. No confetti yet: nobody knows how this ends.
  44. 2. **In flight.** The LED ring chases, the button has a heartbeat, the readout
  45. shows the timer and the latest log line.
  46. 3. **Result.** Success resolves the chord, sweeps the ring green and fires
  47. confetti. Failure shakes the bay, blinks red and shows the error line.
  48. On most Mac keyboards F5 needs `fn` unless "Use F1, F2, etc. keys as standard
  49. function keys" is on in System Settings > Keyboard. Pick a different shortcut in
  50. Settings if you prefer.
  51. Detected automatically when you add a folder:
  52. - `package.json` scripts named `deploy`, `deploy:*`, `ship`, `release`, `publish`
  53. (run with npm, pnpm, yarn or bun, based on the lockfile)
  54. - otherwise `make deploy`, `fly deploy`, `wrangler deploy`, `vercel deploy --prod`,
  55. `netlify deploy --prod`, `firebase deploy` or `./deploy.sh`
  56. - the site URL from `homepage`, `CNAME`, `astro.config`, `next-sitemap`, `wrangler` routes or `fly.toml`
  57. - the icon from `public/`, `app/`, `static/` and similar folders, or from the live website
  58. - two action keys: `health` (a `curl` check of the site URL, also run after every deploy) and
  59. `dev` (the `dev` script, as a service you start and stop)
  60. ## Action keys
  61. Each bay can have up to six small keys under its big button, for the other commands
  62. you run in that folder. Add them in the bay editor (right-click the bay); it also offers
  63. one-click suggestions such as `pull`, `fetch`, `test`, `lint` and `types`.
  64. `ploink-templates.md` lists about 70 more, ready to paste.
  65. | Kind | What the key does | What it shows |
  66. | --- | --- | --- |
  67. | Run once | Runs the command; pass or fail by exit code. | ✓ or ✕, and the result on the readout for a few seconds. |
  68. | Check | Runs the command and shows its last line of output (or a regex capture). | The value, for example `200 · 0.21s` or `34 days`, green or red. |
  69. | Service | Starts a long-running process (dev server, watcher, tunnel). Click again to stop it. | A steady lamp and the localhost port it printed, for example `:5173`. |
  70. Options per key:
  71. - **Hold to run**: for commands that change data (migrations, resets). A click does
  72. nothing; hold the key. Agents always need your approval for these.
  73. - **Agents may press**: lets agents press the key through MCP (`press`). Off by default,
  74. except for the detected health check.
  75. - **After each deploy** (checks only): the deploy shows SHIPPED and fires confetti only
  76. when this check passes. Ploink tries it up to 4 times, 5 seconds apart, because sites
  77. take a moment to come up. If it keeps failing, the deploy ends red with "SITE CHECK FAILED".
  78. Every command also gets `PLOINK_URL` (the bay's website), `PLOINK_PROJECT`,
  79. `PLOINK_BUTTON` and `PLOINK_SOURCE` (`user`, `tray` or `agent`) in its environment.
  80. Services stop when you quit Ploink. Action keys are also in the bay's right-click menu
  81. on the launch bar and in the menu bar item.
  82. ## Flight log
  83. The receipt button in the top bar (or ⌘L, or clicking the status lamp) prints a
  84. plain-English timeline: which project started deploying and when, who started it
  85. (you, an agent, the menu bar), what shipped and how long it took, what failed and
  86. the error line, agent requests that were approved or denied, and projects added
  87. or removed. Filter by failures or agent activity; click a deploy to open its log.
  88. A dot on the button tells you something happened while you were away (red if a
  89. deploy failed). Agents can read the same timeline with the `recent_activity` tool.
  90. ## The launch bar
  91. A slim strip of mini launch buttons that floats over any app, on the display your
  92. mouse is on, including full-screen apps and every Space. Hover a button for its
  93. status, hold it to deploy, right-click for its commands, log, edit and website.
  94. The knob at the start opens the console.
  95. Settings > Buttons (applies to the console and the launch bar):
  96. - **Shape**: round arcade buttons, or square keycaps with a square LED frame.
  97. - **Icon size**: how much of the button the project icon fills, from a small inlay
  98. to an app-icon-sized keycap.
  99. - **Names under launch bar buttons**: on by default, so you can find the right
  100. project at a glance.
  101. Settings > Launch bar:
  102. - **Position**: bottom, top, left, right, or **notch**. In notch mode the bar is a
  103. black island that grows out of the MacBook notch (on displays without a notch it
  104. hangs from the middle of the menu bar).
  105. - **Show it**: on the shortcut (slides away after you launch or click elsewhere),
  106. at the screen edge (push the mouse to that edge, or onto the notch), or always.
  107. - **Style**: **Mini** floats as a slim strip. **Cockpit** is a big console that rises
  108. flush from the screen edge (rounded on the inside corners), with bigger keys and a
  109. readout under each one showing the project and its status. The little lever at the
  110. end of the bar flips between the two.
  111. - **Size**: S, M or L.
  112. - **Shortcut opens**: the launch bar or the console window.
  113. - **Announce results**: when a deploy ends and the console is not in front, the bar
  114. slides in on your current screen, spotlights that project, and shows confetti and
  115. "SHIPPED", or the error with a View log button. It slides away by itself (failures
  116. stay longer, and it waits while you hover). Agent approval requests use the same
  117. spot and stay until you hold the glowing button or click Deny.
  118. - **macOS notifications**: off by default. Turn on if you also want system banners.
  119. ## Lots of projects: banks and type to find
  120. - The launch bar first shrinks its keys to fit the screen. If they still don't fit,
  121. it splits them into banks (A, B, C…), at most 10 keys each.
  122. - Name your own banks in a project's settings (Bank: "Clients", "Side projects").
  123. The console groups projects under bank headers.
  124. - Flip banks with the bank dial (click = next, right-click = previous), ← → or [ ],
  125. or by scrolling over the bar. Keys 1–9 and 0 launch the keys of the bank you see.
  126. - **Type to find**: with the bar open, type part of a name (`lis`, or initials).
  127. Ploink jumps to the right bank and lights up the match. Hold Return to launch it.
  128. Esc clears the search.
  129. ## AI usage gauges
  130. Small gauges on the launch bar (and lamps in the console's top bar) show how much of
  131. your AI plan limits is used. The headline is whichever window is closest to its
  132. limit. Green under 70%, amber from 70% or when usage runs ahead of the clock, red
  133. from 90% or when the limit is reached. Click to refresh, hold to open the provider's
  134. usage page. Agents can read the same numbers with the `ai_usage` tool.
  135. - **Codex / ChatGPT**: read live from the official `codex` CLI (`codex app-server`,
  136. `account/rateLimits/read`), with the newest Codex session log as a fallback.
  137. Needs the Codex CLI signed in with ChatGPT.
  138. - **Claude**: Settings > AI usage > Connect. Ploink sets Claude Code's `statusLine`
  139. to a tiny script that saves only the `rate_limits` numbers Claude Code already
  140. reports (5-hour and weekly), then runs your previous status line command, so it
  141. keeps working. If you had none, you get a small `ploink · 5h 18% · week 62%` line.
  142. It uses only `/bin/sh` and `/usr/bin/plutil`. Disconnect restores your old setting.
  143. The figure updates whenever Claude Code replies.
  144. - **Cursor**: later. There is no public usage source for personal plans.
  145. Ploink never reads, stores or sends passwords, OAuth tokens or cookies.
  146. ## Agents (MCP)
  147. Ploink runs an MCP server on `http://127.0.0.1:47321/mcp` while the app is open.
  148. Every agent needs its own token: **Settings > Agents (MCP) > Create token**. Settings then
  149. shows the setup lines for that agent with a copy button, and you can revoke each token on
  150. its own. Runs and the flight log show which agent pressed what.
  151. Claude Code:
  152. ```bash
  153. claude mcp add --transport http --scope user ploink http://127.0.0.1:47321/mcp --header "Authorization: Bearer plk_…"
  154. ```
  155. If you added Ploink to Claude Code before tokens existed, run
  156. `claude mcp remove --scope user ploink` first. Until you do, Ploink shows a notice when the
  157. old setup tries to connect.
  158. Clients that take JSON config (Cursor, Windsurf and others):
  159. ```json
  160. { "mcpServers": { "ploink": { "url": "http://127.0.0.1:47321/mcp", "headers": { "Authorization": "Bearer plk_…" } } } }
  161. ```
  162. Clients that only speak stdio:
  163. ```json
  164. { "mcpServers": { "ploink": { "command": "node", "args": ["/Applications/Ploink.app/Contents/Resources/app.asar.unpacked/bin/ploink-mcp.mjs"], "env": { "PLOINK_TOKEN": "plk_…" } } } }
  165. ```
  166. Tools:
  167. | Tool | What it does |
  168. | --- | --- |
  169. | `list_projects` | Projects, folders, commands, latest deploy status, and the action keys agents may press. |
  170. | `deploy` | Start a deploy. `project` can be a name, an id, or any path inside the project folder, so an agent can pass its working directory. Optional `command`, `reason`, `wait`. |
  171. | `press` | Press an action key, for example `health` or `pull`. A check returns its value. Pressing a running service stops it. Keys without "Agents may press" are hidden and refused. |
  172. | `wait_for_deploy` | Block until a deploy or key run ends (or a timeout), return status and output tail. |
  173. | `get_deploy_logs` | Full output of a run, or the latest run of a project. |
  174. | `cancel_deploy` | Stop a run, or withdraw a request that waits for approval. |
  175. | `add_project` | Add a folder as a new bay (detection runs like a drag and drop). |
  176. | `deploy_history` | Recent runs of a project. |
  177. | `recent_activity` | The flight log: what started, shipped, failed or was approved, in plain English. |
  178. | `ai_usage` | How much of the Claude and Codex plan limits is used, and when they reset. |
  179. When an agent deploys, the button presses itself in the app and the readout shows
  180. an `AGENT` badge with the reason. If you want to approve agent deploys, set
  181. **Settings > When an agent asks to deploy > Ask me first**, or turn on
  182. **Ask me before agents deploy this** for one project. The button then glows amber
  183. until you hold it (approve) or click **DENY**. Requests expire after 10 minutes.
  184. Agents always need your approval, whatever these settings say, for:
  185. - **Commands an agent added.** `add_project` marks every command and key it creates
  186. (including the scripts it detects) as untrusted. The first agent run waits for your
  187. approval, and you cannot run it yourself until you review it: the bay shows a review
  188. sheet with the exact command. Editing a command in the bay editor also counts as review.
  189. - **Keys marked "hold to run".**
  190. ## How deploys run
  191. - Command runs as `$SHELL -lc "<command>"` in the project folder.
  192. - Environment comes from your interactive login shell (captured once at launch), so
  193. `nvm`, Homebrew, `pnpm` and friends are on `PATH` even when Ploink starts from Finder.
  194. - stdin is closed, so a command that waits for input fails instead of hanging.
  195. - `FORCE_COLOR=1` is set so output keeps its colours in the log drawer. `PLOINK=1`
  196. is set in case your scripts want to know.
  197. - One deploy per project at a time; different projects run in parallel. Action keys have
  198. their own lock, so a health check or a dev server runs while a deploy is busy.
  199. - A deploy is stopped after 30 minutes (`deployTimeoutMin` in the config file).
  200. Config and history live in `~/Library/Application Support/Ploink/`
  201. (`ploink-config.json`, `ploink-history.json`). Ploink used to be called Liftoff: on first
  202. launch it copies your projects and history from `~/Library/Application Support/Liftoff/`.
  203. ## Security notes
  204. The MCP server listens on 127.0.0.1 only. It rejects requests whose `Host` is not
  205. localhost and requests with a non-local `Origin`, so web pages cannot reach it. Every
  206. request also needs a client token (compared in constant time), so other programs on
  207. this Mac cannot press buttons by guessing the port. You can turn tokens off in Settings,
  208. which brings back the old behaviour: any local program can call the server.
  209. Agents can only press buttons you set up. There is no tool that runs an arbitrary
  210. command, and commands an agent adds stay untrusted until you review them (see above).
  211. Note that a trusted command such as `npm run deploy` runs whatever that script says
  212. at the time, so an agent that can edit the repo can still change what it does.
  213. `ploink-config.json` holds the tokens and your commands, so Ploink writes it readable
  214. only by your user (mode 600).
  215. ## Development
  216. ```bash
  217. npm run preview # the UI in a normal browser with fake projects and fake deploys
  218. npm test # runner, detection and project matching tests
  219. ```
  220. In preview, `window.__mock.agent(3, 'reason')` simulates an agent request.
  221. Open `/bar.html?edge=bottom` (or `top`, `left`, `right`, `notch`) to see the
  222. launch bar; `window.__mock.announce(0, 'success')` shows an announcement.
  223. Useful environment variables for `npm start`:
  224. - `PLOINK_USER_DATA=/some/dir`: use a separate config, for testing.
  225. - `PLOINK_SHOTS=/some/dir`: `kill -USR2 <pid>` saves screenshots of the console
  226. and the launch bar there, and `kill -USR1 <pid>` acts like pressing the shortcut.
  227. Layout:
  228. ```
  229. main/main.mjs console window, global shortcut, menu bar item, IPC
  230. main/bar.mjs launch bar window: edges, notch, cockpit, banks, show/hide, hot edge
  231. main/usage.mjs AI usage: Claude status line hook, codex app-server
  232. main/runner.mjs runs deploys, streams output, approvals, history
  233. main/mcp.mjs MCP server (Streamable HTTP, stateless)
  234. main/detect.mjs reads a project folder: name, commands, URL, icon
  235. main/favicon.mjs fetches the best icon from a website
  236. main/shellenv.mjs captures your login shell environment
  237. renderer/app.js the console UI
  238. renderer/bar.* the launch bar UI
  239. renderer/styles.css the look
  240. renderer/audio.js synthesized sounds (WebAudio, no sample files)
  241. renderer/fx.js sparks, shockwaves and confetti
  242. renderer/mock.js fake bridge for npm run preview
  243. bin/ploink-mcp.mjs stdio-to-HTTP bridge for stdio-only MCP clients
  244. build/ app icon and menu bar icon sources
  245. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.