Design decisions and Phase 0 · Jot for Mac
Written 2026-09-01 against main @ b99f328
(v1.20.1). Design only, no code. Covers what the repo can't tell you: external
research, the sensor decision, and the spike that gates everything else — for what
Jot is, the architecture layers and the ship checklist, read CLAUDE.md.
Markdown version →
Caveat on everything below. Authored on a Linux box with no Swift
toolchain. Nothing here has been compiled or run, and line references were accurate
at b99f328. Re-check them.
Not approved for implementation. Two owner decisions block it (§6, items 1–2).
Phase 0 (§4) is the only authorized work. It's a throwaway standalone CLI that commits to nothing. Do it, report the data, stop.
A new trigger: double-slap the chassis to start dictation, slap again to
stop. New trigger source against the existing recorder.toggle() seam —
nothing in the Recording, Transcription, LLM, or Delivery layers changes.
The gap it fills: every current trigger assumes fingers on home row. The compelling moments are the ones where your hands aren't.
Origin is an r/SideProject post — "Slap to talk: I've trained my mac to detect double slap and use it for dictation." That author used the microphone plus a trained classifier. §3 is why we're not doing that.
Apple Silicon MacBooks (M1–M4) ship a MEMS accelerometer + gyroscope driven by the Sensor Processing Unit, readable over IOKit HID at up to 800 Hz. Entirely undocumented — not in CoreMotion, not in any public framework — but readable. Reference implementation:
Descendant of the Sudden Motion Sensor, which stopped being exposed rather than being removed during the SSD transition.
Two things make it usable here specifically:
Resources/Jot.entitlements has
com.apple.security.app-sandbox = false; Jot ships Developer
ID + notarized DMG via Sparkle, not MAS. No sandbox blocking IOKit, no reviewer to
reject an undocumented interface. Non-starter for a sandboxed app.Sources/Permissions/PermissionsService.swift:6 imports it for the Input
Monitoring capability.| Microphone | Accelerometer | |
|---|---|---|
| API status | Public, stable | Undocumented; may break on any macOS release |
| Hardware reach | Every Mac | MacBooks only |
| Orange mic indicator | Permanently lit | Never |
| Discrimination vs. typing | Severe problem | Mild |
Contends with AudioCapture | Yes — AUHAL unit, pinned device | No |
| Breaks if user picks a USB mic | Yes | No |
| Violates the stated non-goal | Directly | Arguably not (§5) |
The deciding row is typing. A false trigger isn't cosmetic — the pipeline ends in synthetic ⌘V at the cursor, so it can inject text into the document someone is working in. A keystroke is a sharp broadband transient, and two keys ~200 ms apart is ordinary typing cadence. Separating "deliberate slap" from "keystroke" in audio is the whole difficulty — it's why the Reddit author needed a trained model.
The accelerometer measures the right physical quantity: a palm slap is a large, low-frequency, whole-chassis impulse; a keypress is small, damped, localized.
That's a physics argument, not a measurement. Confirming it is what Phase 0 is for.
Pre-check, ten seconds:
ioreg -l | grep -i "AppleSPU"
ioreg -r -c IOHIDDevice -l | grep -i -B5 -A5 'accel\|gyro'
Nothing enumerates → stop and report; the accelerometer path is dead on this hardware and the decision reverts to the mic.
Deliverable: standalone Swift CLI (~150 lines) that opens the SPU
HID device and dumps timestamped 3-axis readings as CSV. Build it with
swiftc or a scratch SPM package — not in the Jot Xcode
target. Use the §2 reference implementation for the HID matching dictionary and report
parsing; don't reinvent it.
Three questions:
Question 3 decides the feature. If typing and slapping overlap the way they do in audio, the DSP-first plan collapses and this becomes an ML project.
Report back: the traces, peak deviation magnitude and rise time per gesture class, model identifier + macOS version + whether any TCC prompt appeared, and your honest read on whether a threshold state machine can hit zero false positives over a workday of typing.
Do not proceed to Phase 1 on your own initiative.
docs/design-requirements.md:126 lists "Voice-activity-detection /
continuous listening modes" under Out of Scope, prefaced "should not be reintroduced
without a new intent brief."
The mic path violates it head-on. The accelerometer path arguably doesn't — no audio is captured — but it still adds a persistent always-on ambient input modality, which is what the constraint guards. Either way it needs a dated amendment before implementation. Proposed:
Ambient triggers may use non-audio sensors. Slap-to-talk reads the chassis accelerometer. The microphone stays closed until a dictation starts; the "no continuous listening" non-goal is specifically about audio and is unchanged. (Decision: 2026-09-01 — a non-audio trigger carries none of the privacy cost the original non-goal was written to prevent.)
Owner's call. Don't make it.
features.shortcuts-pane-redesign —
that item makes trigger type first-class, and a slap is naturally one. Land it
first, or accept rework. Don't do them concurrently.ML is a large fixed cost (training data, a bundled CoreML asset, a retraining story). Let Phase 0 data decide. Starting parameters, all guesses to be tuned against real traces:
Gating: suspend when display asleep / locked, lid closed, a dictation or Rewrite or Transform is in flight, or the feature is off.
Sources/Overlay/PillViewModel.swift:35-42 —
PillState.savedToRecents(preview:) already ships (v1.14): recording stopped
without pasting, clickable, opens Recents.
A slap-triggered recording that transcribes to empty or near-silent must
never paste. It resolves to savedToRecents.
Drops the worst-case false positive from "garbage in your document" to "a pill blinked." Phase 1, not polish.
TapDetector must be pure Foundation over a stream of readings — no IOKit,
no clocks, no actors — so Phase 0 traces become golden fixtures.
SPUAccelerometerSource is the only platform-coupled file, behind a protocol
seam. Sources/ is a synchronized folder group, so no
project.pbxproj edits.
Sensor enumeration failure → disable the feature and post a one-time notice. Never crash, never spin retrying. Build that in from the start.
Off by default, behind ExperimentalBadge. Settings → Shortcuts. One
user-facing parameter: sensitivity (Light / Medium / Firm). Section hidden,
not disabled, on non-MacBook hardware.
Calibration view is non-negotiable — threshold depends on the desk, the feet, and how hard they hit. Live meter, "slap twice now", ~5 samples → proposed threshold, and a false-positive counter running while the user types for 15 seconds. That last one is the check that matters and the one nobody would think to run.
No Setup Wizard step.
| Phase | Gate |
|---|---|
| 0. Spike ← you are here | Do the signals separate? |
1. Core — detector + source + recorder.toggle(), no UI, DEBUG-only, §7 safety rule | Fires when slapped, silent for a workday of typing? |
| 2. UX — settings, sensitivity, calibration, Help | Owner review |
| 3. Polish — adaptive floor, power gating, sensor-absent handling | Ship experimental, off by default |
Phase 1 is the real go/no-go. Zero false positives over a workday of typing is the bar; anything less isn't shippable given the paste path.