Docs

How to use Runnock, from install to uninstall.

Quick start

Download the disk image from runnock.com, drag Runnock to Applications and open it from there. It needs macOS 26 or later and Apple silicon. On a screen without a notch Runnock draws one at the top.

On first launch it looks for the coding agents on your Mac and asks in the notch whether to connect them: press Connect all. Its hooks go in next to yours, after a backup.

You can try it free for 14 days from the first time you open it, with every feature, no account and no card. In the last 3 days a card in the notch tells you how many days are left, and Settings, License and the menu bar icon always show it. After that Runnock stays locked until a license is activated.

Buying and activating

Buy on the website and the key arrives by email. Open Settings, go to License, paste the key and press Activate. How many Macs a key works on depends on the plan you bought (2, 4 or 6).

To move a key to another Mac, press Deactivate on this one first, which frees the seat.

Runnock checks the license once a day. Without a connection it keeps working for 30 days after the last successful check, and in the last 7 days a card in the notch asks you to connect. Refunds are on the Refunds page.

Reading the notch

Collapsed, the notch gives one state and a word. One glance is enough:

  • Working: The agent and its state, how long it has been at it, and the task itself, which rolls through what it said and what it is touching.
  • Needs you: A pixel question mark when it is waiting for your answer.
  • Done: A green check the moment a task finishes.
  • Failed: A red mark for a failed build, test or command.
  • Listening: A dev server that is up, with its port.

Each finished task, failed build or waiting agent separates from the notch like a drop and hangs below it, with a small tail pointing back. It is drawn the same way in the app: no video, no trick.

Click the notch or a bubble to open it. At most 3 bubbles show at once. What you can do once it is open depends on what it is: approve, answer, see what changed, open a link.

Connecting agents

Works with: Claude Code, Codex, Grok Build, Command Code, Devin, Qwen Code, GitHub Copilot CLI, pi, Kimi Code.

Connect or disconnect an agent any time under Agents in Settings.

  • Codex: after connecting, run /hooks in Codex once and trust the Runnock entries.
  • Grok Build and GitHub Copilot CLI: restart running sessions after connecting.
  • pi: run /reload in pi after connecting, or restart it. pi has no approval prompts, so it reports status only.

On disconnecting or uninstalling, Runnock removes only the entries it added.

Approvals and questions

When Claude Code, Codex and others ask for permission, the prompt opens in the notch with the command in plain sight. Allow it, always allow it, deny it, or send it back to the terminal. When Claude Code or Grok Build ask you a multiple-choice question, answer that in the notch too: pick one, tick several, or type your own. Anything Runnock cannot answer falls back to the agent's own prompt, so nothing is ever stuck.

When an agent asks for permission the prompt opens in the notch with the command in plain sight. Allow it, always allow it, deny it, or press Terminal to hand it back to the agent's own prompt. When Claude Code or Grok Build ask a multiple-choice question it opens in the notch too: one tap answers a single-choice question, tick several and press Done for a multiple-choice one, or press Other… to type your own.

Claude Code

Claude Code tells Runnock far more than "working" and "done". The island uses it.

  • Compacting: A /compact you asked for and one Claude started itself are told apart. Yours ends with a check instead of staying on "working".
  • Tasks, model, subagents: Its own task list as 2/5, the model it is on, and how many subagents are running.
  • Why it stopped: A rate limit, a sign-in problem or a billing error is named, not just "failed". When the limit resets and Claude carries on by itself, it says that too. A session that went quiet can be ignored until it speaks again.

Watch the work, not just the status.

Open the notch while Claude Code works and the conversation is there: what you asked, with any pictures you sent, what it said, drawn as Markdown, and every tool call with how it came out. A call opens to show what it printed, and a file edit shows its diff with line numbers. It follows along as it grows, and the card is as tall as it needs to be before anything scrolls.

Claude Code only for now. Runnock reads the end of the conversation file Claude Code keeps on your Mac and shows it on screen. It is held in memory, never written down or uploaded; secrets in text are masked, a picture is shown as it is. Switch it off in Settings and the file is not opened.

What a turn changed

When a turn ends, a bubble says how many files changed and by how many lines. Open it for the list, then any file for its diff, in a window of its own. Runnock compares your work tree from before the turn with the one after it, so every agent gets this, and your repository's index, branch and stash are never touched.

It needs a git repository, and can be switched off under Notch in Settings.

Usage limits

Runnock tells you when Codex, Claude Code, Grok or Devin is down to 50%, 20% and 5% of a limit, when it runs out and when it comes back, and when it is usable again.

Codex is read from its own session files. Claude Code and Grok are asked with the sign-in they keep on your Mac, and macOS may ask once to allow it. Devin is asked with the sign-in Devin Desktop or the Devin CLI keeps, which only goes to Devin's own server. You can switch it off in Settings.

The panel the menu bar icon opens shows each provider's limits as a bar, and the bar and the figure are what is left: green above 50%, yellow down to 20%, orange down to 5%, red at 5% or less. A refresh button in its title row reads them again at once, and General in Settings chooses which providers it shows.

Servers, builds, Git and deployments

Dev servers: Start one from a project folder. It appears with its port, an Open button and a Kill button. Docker containers and Compose projects are watched too. Builds and tests: Xcode builds, test runs and any zsh command that takes a while report back with the error count or the line that failed.

With the gh command you already use, Runnock reads your GitHub notifications for pull requests (a review asked of you, changes requested, a mention, an approval or a merge), follows a CI run from start to red or green, and watches the deployment of a repository you chose: Vercel, Cloudflare Pages and Netlify show up while they build, and again when they go live or fail, with the line that broke. Merge conflicts need no login at all. Each one is a line on the island that goes away when it is over.

  • Review requested: A pull request is waiting for you. It stays until you have read it on GitHub.
  • Changes requested: A reviewer wants changes on your pull request, with its title and number.
  • Merged: Approvals, merges and mentions arrive too, and the ones that are only news fade on their own.
  • CI failed: The workflow that failed, and the branch it ran on.
  • CI passed: A green check after a red one or a run you watched, and nothing for runs you did not.
  • Merge conflict: A merge, rebase or cherry-pick stopped by conflicts, with the number of files.
  • Deploying: The environment and the commit, with a timer while it builds.
  • Deploy failed: The reason from the platform, so you do not open the dashboard to find it.
  • Live: A moment on the island when what you watched goes live, then it leaves.

Every source is a switch in Settings, and nothing runs that you did not turn on.

Clipboard context

Off by default. Switch it on under Notch in Settings, then copy a stack trace, some JSON or a colour and the notch offers a tidy-up. It opens when you click it, and writes to the clipboard only when you press Copy. Anything that looks like a key only flashes a lock. Nothing is kept or sent, and there is no history.

Pushing a status from a script

First press Install next to Command under Build & Test in Settings, which puts the runnock command in ~/.local/bin, and check that External alerts is on (under Notch in Settings, on by default). Then:

runnock alert --title tests --body "3 failed" --level fail --open "$PWD"

It hands the request to the running Runnock over a local socket: no network port is opened, nothing is queued and nothing is written. The options:

OptionWhat it does
--titleRequired. Plain text, 1 to 16 characters.
--bodyPlain text, up to 80 characters.
--levelinfo (the default, 4 seconds), action (30 seconds) or fail (until dismissed).
--openA path under your home folder or /tmp. Open shows it in Finder; nothing is ever run.
--idA new alert with the same id replaces the old one instead of adding one.
--ttlHow long it stays, 0 to 86400 seconds. 0 uses the level's own.
--lineAn extra line shown when it is opened, up to 60 characters. Repeat it for up to 4 lines.
--markA small mark beside the title. For now only dodo.
--hold0 to 60 seconds: hold the main island for that long, above an agent's work and its failures but never above an approval.
--clear <id>Takes down the alert pushed with that id.

Exit codes: 0 shown, 1 Runnock is not running, 2 External alerts is switched off, 3 the request was refused (the reason is printed on stderr), 4 anything else.

Shortcuts can use a runnock://alert?title=…&level=… link with the same options, except that it does not take hold.

Recipes

Small scripts that put a line on the island: when a push is done, a command ends, the disk is filling up. Copy one, and it works. Each does one thing, and none of them updates itself or downloads anything.

runnock recipe list
runnock recipe show timer
runnock recipe install timer
runnock recipe uninstall timer

Before installing it lists what it will do and asks. It backs up ~/.zshrc before touching it, and uninstall takes out exactly what install put in. The full list, with the scripts, is on the Recipes page.

Dodo Payments notices

If you sell with Dodo Payments, the notch can say when a payment succeeds: the amount is in the title (for example Paid 27519.00, shown for 15 seconds), and opening it shows who paid (name and email), whether it was a new purchase or a renewal, and the card brand (never the number). It reads your own Dodo account from your own Mac, once a minute, with a key only you hold; nothing goes through a Runnock server.

  1. In the Dodo dashboard, under Developer → API Keys, make a key just for this, with Payments set to Read. Test and live keys are separate.
  2. Run runnock dodo setup (add --test for the test environment). It asks for the key (not shown as you type), reads Dodo once to check it, and keeps it in the keychain. Payments that already exist become history and are not announced.
  3. Run runnock recipe install dodo-payments, which installs the background job that runs once a minute.
CommandWhat it does
runnock dodo statusShows where things stand.
runnock dodo config --hide-amountLeaves out the amount and everything about the customer and the order (--show-amount undoes it).
runnock dodo config --hide-customerLeaves out the name and email (--show-customer undoes it).
runnock dodo config --hide-detailsLeaves out new/renewal and the card brand (--show-details undoes it).
runnock recipe uninstall dodo-paymentsStops the background job.
runnock dodo resetDeletes the key from the keychain and everything remembered.

Good to know: nothing is asked of Dodo while Runnock is not running or the Mac sleeps. When Runnock is back it looks at the last 7 days, and a payment older than 48 hours is no longer announced. A notice can be up to a minute late. Name, email and card brand are only in memory at the moment of showing and are never written to disk. For now it is set up from the command line.

Settings

Every source is a switch, every alert has its own sound, and nothing runs that you did not turn on.

  • General: language, checking for updates, the fallback terminal, which providers the menu bar panel shows, and Remove all hooks.
  • Agents: connect or disconnect each agent.
  • Notch: which screen it is on, sounds, what a turn changed, usage alerts, clipboard context, external alerts.
  • Build & Test: installing the runnock command, long-running commands.
  • License: activate, deactivate, trial days left.
  • About: the website and where to send feedback.

Permissions and privacy

Runnock needs to read Documents, Desktop and Downloads to see changes in Git repositories kept there. macOS asks once; allow it. If you decline, Git activity in those folders is not shown, and you can add the access later under System Settings, Privacy & Security, Full Disk Access.

What the agents report, and the messages you send them, stay in Runnock's own folder on your Mac and are not sent anywhere. Runnock has no analytics, telemetry or crash reporting. The Privacy page has the full account.

Uninstall

  1. In Settings, License, press Deactivate, so the seat is free for another Mac.
  2. In Settings, General, press Remove all hooks. Runnock disconnects every agent and cleans up its entries.
  3. If you turned on Long-running commands (Build & Test in Settings), turn it off first; Runnock then removes its lines from ~/.zshrc. If you installed recipes, take them out one by one with runnock recipe uninstall; if you used Dodo Payments notices, also run runnock dodo reset.
  4. Quit Runnock and drag it from Applications to the Trash. If you installed the runnock command, delete ~/.local/bin/runnock too.
  5. To remove everything, delete the folder ~/Library/Application Support/Runnock.

Something wrong

Start with the Help page. If that does not settle it, write to [email protected], ideally with your macOS version, which agent you use and what happened.