I'm Zak, and I build InkHammy, a grammar checker that runs as a Mac menu bar app and as an iPhone keyboard. Disclosure up front: InkHammy is my product. This post isn't a review; it's a write-up of how the Mac app reads and fixes text inside other apps through the macOS Accessibility API, and the design choices that came out of it.
The problem
A browser extension only sees web pages. A lot of writing on a Mac happens somewhere else: Slack, Mail, Notes, Messages, the ChatGPT app, and text fields inside desktop apps built on web views. To check text in all of them, an app has to follow whichever field has focus, read its text, know where each word sits on screen, and write corrections back without breaking the host app.
macOS exposes this through the Accessibility API (AX). The user grants Accessibility permission once in System Settings, and the app can then observe and act on UI elements in other processes. AX is powerful, but every host app implements it a little differently, and a call into a busy app can block. Most of InkHammy's Mac architecture exists to deal with those two facts.
Client and server have separate jobs
The Mac client doesn't decide what is wrong with the text. All correction processing lives in the backend. The client detects the text being written, sends it with read-only context, and applies the ranges that come back only after re-checking that the text has not changed in the meantime.
That split keeps the client's job mechanical: observe, send, draw, and write back when the user asks.
Following the focused field
The core object on macOS is FieldSessionCoordinator. It follows the focused field and coordinates four collaborators, each with one job:
-
FieldObserverturns Accessibility notifications into polls. A notification is treated as a hint that something may have changed, not as the source of truth. -
FieldSessionMachinedecides what each poll means, as a pure function: given the current state and what the poll read, it returns the next state and the action to take. With no side effects, it can be tested without driving a real app. -
AnalysisSchedulerowns requests to the server and the cache, so the same text isn't checked twice and an old response can't overwrite a newer one. -
OverlayPresenterdraws the badge, the underlines and the review card in an overlay above the host app.
Turning notifications into polls matters because notifications aren't consistent from one app to the next. A poll that reads the current state and hands it to a pure state machine behaves the same way no matter which path triggered it.
A hung app must not freeze InkHammy
An AX call is a synchronous request to another process. If that process is stuck, the call waits. If those calls ran on the main thread, one frozen app would freeze InkHammy's menu bar and overlay along with it.
So every Accessibility call runs on its own AXActor queue. The rest of the app talks to that actor. If a host app stops responding, only the AX work waits; everything else keeps running.
Web fields are different
Text fields inside browsers and web-view apps are web content exposed through AX, and they behave differently from native text views. InkHammy detects them from their AXWebArea. Per-app behaviour lives in one place, AppCompatibility: web field detection, a short list of verified exceptions, and each app's send key.
Writing a fix back
Reading text is the easy half. Writing into another app's text field safely is where most of the care goes, and InkHammy never edits text on its own: a fix is applied only when the user asks for it, by FieldWriter.
FieldWriter applies fixes one range at a time, last range first. Working from the end of the text toward the start means applying one fix doesn't shift the offsets of the fixes that come before it. For each range it:
- selects the exact range,
- verifies the selection,
- sets the new text, or, where a host app ignores the setter, pastes over just that range,
- reads the text back to confirm the change landed,
- restores the caret.
The select, verify, set, read back sequence exists because an AX write can fail without an error. Reading back after every write is how the app knows a fix actually happened, instead of assuming it did.
The send guard
InkHammy can also catch typos at the moment you press send in Slack, Messages or Mail. KeyEventTap, a session event tap, owns the review card's keyboard shortcuts and the send guard, so those keys never leak into the host app. SendGuardPolicy decides what happens with each send key press, using the send key AppCompatibility records for that app.
From a model's output to safe ranges
On the server, a fast check streams the corrected text from the model. The server diffs that text against the original and turns the differences into exact UTF-16 ranges, the unit both Swift's NSString APIs and the Accessibility API use for text offsets. Before anything reaches the client, the ranges are validated: protected content such as URLs, numbers, code, quotes and emoji must not change. The server pushes each fix as soon as the model has written past it, then sends the full response.
The client receives ranges, not a rewritten paragraph. That is what lets FieldWriter touch only the words being fixed and leave the rest of the field, and the user's formatting, alone.
If you're building something similar
- Treat AX notifications as hints and re-read the state yourself.
- Put every AX call behind an actor or a dedicated queue, so a hung app can't take yours down.
- Verify every write by reading it back.
- Apply multiple edits from the end of the text toward the start.
- Keep the decision logic pure, so you can test it without real apps.
- Keep per-app quirks in one table instead of scattering special cases through the code.
If you've worked with AX and found other patterns that hold up across apps, I'd like to hear them in the comments.
If you want to try it in your own apps, InkHammy for Mac is here: https://inkhammy.com/mac
Top comments (1)
Reading back after every write is the part I’d underline too. Two things bit me doing the same in my own Mac app:
In WebKit fields (Safari, Mail, web views), setting
AXValuecan return success while the text lands in whichever field has the page’s focus, and reading the asked field back can still show the new value. What held up for me: setAXFocused, wait until the app’s focused element really is that field, then type, then check that the other fields did not change.For underlines in Electron and Chromium fields,
AXBoundsForRangeon the field answers with no error and a zero-size rect. TheAXStaticTextleaves inside the field give real rects, so I map the range onto those leaves. Chromium also needsAXManualAccessibilityset before the tree shows any content.How do you keep the underlines in place when the host field scrolls?