Record a call locally: Hex captures the other participants (system audio) and
you (microphone) as separate tracks, transcribes them on this Mac, and saves a
Markdown transcript with You and Them turns. Recording starts automatically
only for calls from a website or app set to Always record, and never stops
automatically unless Labs › Stop when the call ends is on (see
meetings.auto-stop). This map describes macOS; Linux and Windows
lists where they differ.
Linked checks are locators unless an executed result is recorded below.
Labs > Meetings switch (macOS) // meetings.opt-in; off by default
├── Off -> only the Labs switch -> Turn on -> meetings.enabled = true
├── On -> Meetings joins the sidebar; header switch Recordings | Settings;
│ menu-bar items, call detection, Option-Control-V
│ Settings view: Call recording, Calendar, Detected calls, Advanced ▸
│ ├── System Audio Recording // meetings.permission; asked only now
│ │ ├── Untrusted row shown / Allow -> retired Hex IDs cleared (`ScreenCapture` + `AudioCapture`)
│ │ ├── Allow -> macOS prompt the first time (tour's permission_control)
│ │ ├── Decided before -> Privacy pane + drag guide ("System Audio Recording Only")
│ │ ├── Asked -> pulse; TCC preflight re-read on each poll, no reopen needed
│ │ ├── Returned from System Settings still untrusted -> "Still grey? Fix it"
│ │ │ (`AudioCapture` reset on running bundle + retired IDs, re-prompt / guide)
│ │ └── Granted -> the Allow pill morphs into a green Allowed; moves to Advanced
│ ├── Advanced -> Show recording indicator (on by default; corner-snapping capsule),
│ │ Transcript folder (~/Documents/Hex Meetings; Reveal / choose; an error opens
│ │ Advanced), Summarize with Apple Intelligence (on by default), Summarize
│ │ with OpenCode (off by default; when Apple Intelligence is off or missing)
│ ├── Calendar -> Connect calendar; reminders before meetings // meetings.calendar
│ └── Detected calls -> Ask / Always record / Never offer per provider // meetings.policy
│ ├── Slack huddles, Zoom, Google Meet, Microsoft Teams, FaceTime, WhatsApp,
│ │ Gather (always listed)
│ └── then each website or app chosen for from an offer's "…"
└── Off -> Controller idles; no microphone-activity inspection or shortcut;
the pane leaves the sidebar
Debug builds -> Always in the sidebar (DEVELOPER_FEATURES_ENABLED)
Agents -> hex mcp (read-only MCP server; works whether or not Meetings is on)
Subtitles -> hex meetings show <id> --srt | --vtt // Labs › Subtitle export, off by default (#633)
one cue per transcript entry (You / Them), timed by entry offsets,
not word timings; off -> refused naming hex labs on subtitle-export
(docs/transcript-cli.md; no export button in the window yet)Requires the selected local dictation model, Microphone, and System Audio
Recording (the "System Audio Recording Only" list under Privacy & Security ›
Screen & System Audio Recording; NSAudioCaptureUsageDescription). Screen
Recording alone still works through the ScreenCaptureKit fallback. The opt-in is meetings.enabled in settings.json, alongside
meetings.show_recording_indicator (default true) and
meetings.recording_indicator_corner (default top_right)
(app_settings.rs MeetingSettings). Recording
refuses to start without either grant and asks macOS for System Audio Recording.
The same controller, recorder, transcript pipeline, store, pane, capsules, and notes run on Linux and Windows (beta, in Labs, off by default). Only these adapters differ (meeting/linux.rs, meeting/windows.rs, microphone_activity/linux.rs, microphone_activity/windows.rs, meeting/runtime.rs):
System audio // meetings.system-audio
├── Linux -> pw-record of the default output's monitor (stream.capture.sink);
│ the session manager follows a changed default; no pw-record -> recording
│ refuses with "Install PipeWire's pw-record"
└── Windows -> WASAPI loopback of the default output (cpal); silence while
nothing plays is padded on resume; a changed default reopens it
Call detection // meetings.detect
├── Linux -> one pw-dump --monitor: running Stream/Input/Audio nodes that are
│ not monitor captures, by application.process.binary (node or client)
└── Windows -> active IAudioSessionManager2 sessions on every capture device,
by process image name
└── executables map to the macOS keys (zoom -> us.zoom.xos, chrome ->
com.google.Chrome, ms-teams.exe -> com.microsoft.teams2, ...)
Browser calls -> offered as "Call in <browser>": no site is read yet
Permissions -> none asked; the System Audio Recording row is macOS-only
Calendar -> none (no Connect calendar row)
Notes and live chapters -> Summarize with OpenCode (off by default); it sends
the transcript excerpt to the OpenCode model
Idle sleep -> systemd-inhibit idle:sleep (Linux),
SetThreadExecutionState (Windows) while recording
Tray -> Record meeting, Stop & transcribe, Copy last meeting transcript
while Meetings is on
Quit while recording -> audio kept; the transcript finishes at the next launch
Files -> Reveal opens the folder (xdg-open, Explorer); Delete moves to the
freedesktop Trash or the Recycle BinThe pane's Start recording, Stop & transcribe, Rename, Delete, Reveal, and
Summarize run in the window's own process there. Until
#566 they went to the OS host,
which ignored meeting requests, so a deleted recording stayed listed and no
error showed. Check: pane_requests_reach_the_window_s_own_meetings in
rune_ui/meetings.rs; a Recycle Bin delete on
a real Windows PC has not been observed.
Not on Linux and Windows yet: the Option-Control-V meeting paste shortcut,
Copy section from the tray, dragging the recording capsule to another corner,
the hex meetings and hex mcp commands (shared-control), and website names
for browser calls. Verified: Linux and Windows x64 build and lint
(cargo clippy, cargo xwin clippy); the PipeWire monitor capture and
pw-dump parsing were checked by hand on Arch/niri. Not verified: a recorded
call end to end on either OS, Windows loopback and session detection on
hardware.
Zoom / Teams / Slack huddle / FaceTime / WhatsApp / browser call uses the microphone
(WhatsApp: net.whatsapp.WhatsApp, the older desktop.WhatsApp, WhatsApp.exe or
WhatsApp.Root.exe on Windows, web.whatsapp.com in a browser; 20 s, as voice
notes also hold the microphone; Gather: com.gather.GatherV2 and its helpers,
com.gather.Gather, Gather.exe, app.v2.gather.town and app.gather.town; 20 s,
as sitting in a space can hold it)
-> CoreAudio input process -> canonical host app // parent PID + bundle ID
-> On the microphone for 2 s by the monotonic clock // meetings.detect
│ Google Meet and Banshee (banshee.app) in a browser count as known
│ services; a slow watcher loop never stretches the time
└── Browser on a page that is not a known call site -> 20 s,
so voice notes and dictation fields are not offered
-> Provider = the website when known, else the app; the website's choice
when it has one, else the app's (a browser's choice covers its other
sites), else Ask
├── Never offer -> nothing shown; an earlier offer stays snoozed
├── Always record -> starts recording, no offer // meetings.auto-record
│ └── recording capsule says "Started automatically" for 10 s; with the
│ indicator off, a "Recording automatically" capsule with Stop
│ and ✕ (✕ only hides it; the recording goes on, in the menu bar)
└── Ask -> Capsule below the menu bar, focus-free // meetings.offer
├── Title: "Google Meet call detected", "Call on meet.jit.si",
│ "Call in Brave Browser" (site unknown), or the meeting's name
├── Record -> Start recording
├── Not now -> Close
├── … -> "<provider>" · "Change anytime in Settings" (capsule widens)
│ ├── Never offer -> saved, close
│ ├── Always record -> saved, records this call too
│ │ └── not offered for a browser on an unknown page
│ └── Cancel
└── 20 s timeout -> Close // never records on timeout
-> Same call is snoozed by key and app until off the microphone for 60 s,
offered or recorded; stopping an automatic recording does not restart it
└── Absence counts from the last time the call app was on the microphone,
a gap included (sleep, Meetings off, a recording): an app that left
the microphone during a recording is not snoozed for another minute
-> "Left the call" prompt after the call app is off the microphone for 3 s
-> Times are wall-clock runs: observations more than 10 s apart (sleep, a
stalled loop) start a stability run again instead of counting the gap
└── A call off the microphone for at most 2 s (a missed check) keeps
its run; a longer release starts it over
Choices persist as `meetings.providers` (`key`, `label`, `policy`:
`ask` / `always_record` / `never_offer`) in `settings.json`. Missing means Ask.
The older `meetings.never_offer` list reads as Never offer entries and is
rewritten as `providers` on the next load.Call detection knows Brave, Chrome, Safari, Firefox, Edge, and Arc
(company.thebrowser.Browser, foreground name Arc; its tab is read like
Brave's). Arc was missing until #801, so its Meet calls were never detected.
Check: a_google_meet_call_in_arc_records_after_about_two_seconds.
Chromium and Electron apps (Brave, Chrome, Edge, Arc, Slack, Teams) capture microphone
audio in sandboxed audio.mojom.AudioService utility processes (*.helper) that
do not register with NSRunningApplication; Zoom uses us.zoom.CptHost, Firefox
uses org.mozilla.plugincontainer, Safari uses com.apple.WebKit.GPU (Safari Graphics and Media), and FaceTime uses com.apple.avconferenced.
microphone_activity.rs attributes each input
process to its canonical host app via parent PID lineage, CoreAudio's
kAudioProcessPropertyBundleID, and NSRunningApplication. When Brave uses the
microphone and is not snoozed, ContextSnapshot::capture_for_meeting in
dictation/context.rs reads the active tab of Brave's front window,
even if Brave is behind another window. When that AppleScript read fails or
answers nothing (Automation not allowed, a failing script; #827, Arc), the
page comes from the browser process's focused web area through Accessibility
(AXURL), still behind another window; the first failure per browser is
logged as could not read the browser tab. Arc (and other Chromium browsers)
behind another app often exposes no web area either, so without a page the
browser's own focused window title is used: a tab titled Meet - … /
Meet – … counts as a Google Meet call on meet.google.com (2 s, Always
record applies); the landing page ("Google Meet") does not. Before this, a
Meet call in a background Arc without Automation was an unnamed browser call
(#827). Check:
a_google_meet_call_in_arc_without_its_address_is_known_by_its_title; not yet
observed against a live background Arc. Background tabs are not searched: a
call open in one says nothing about which tab holds the microphone, and a
voice note elsewhere would otherwise get a known service's 2 s threshold or
trigger Always record. (A call in a background tab is therefore judged by the
active tab's page, which is the unknown-page 20 s for a new site.) That query is
an AppleScript round trip, so the watcher starts it on its own
thread (at most one at a time, about once a second) and reads the newest answer,
at most 5 s after it finished; a slow or timed-out query (the existing 2 s
limit) never holds up the loop. Answers and the remembered page are dropped
while Hex records, Meetings is off, the browser is snoozed, or no browser holds
the microphone; a query in flight at that moment is not repeated beside itself,
and its answer is discarded. When a browser's page is found for a run already
under way (the first pass had no answer yet), the run keeps counting, now
toward the known service's 2 s. When no answer names a page, the last page a browser showed while
it held the microphone names the call for 60 s (BrowserPageMemory), so the
site survives a failed query or Hex being in front. Safari, Chrome, Firefox and
Edge expose no URL, so their calls are unnamed unless the foreground context
says otherwise. Banshee has no recognised room path, so any banshee.app page
counts; it is not in Settings' always-listed providers, but appears under
Detected calls once its choice is set from an offer's "…". Not observed: the
new tab query against a live Brave with a Banshee call (the script compiles, and
the thread and memory are unit-tested with fake queries); the Banshee URL shape
was not available, so the host rule is a guess at "any page".
On 2026-10-21 Brave opened the microphone for 3-6 s at a time on
problems.kitlangton.com (board voice notes) and each burst got a "Browser call
call detected" offer; that is what the 20 s browser threshold prevents.
A second Banshee call on 2026-10-26 got no offer in the 30 s before Kit started
recording by hand: the "about 20 s" threshold was 40 loop observations, and each
loop took about 0.9 s (500 ms sleep plus the browser inspection), so an unknown
browser page needed about 37 s. The thresholds are now clock time.
Checks: a_slow_loop_still_offers_an_unknown_browser_call_after_about_20_seconds,
a_slow_loop_still_ends_a_snooze_after_a_minute,
a_stalled_loop_does_not_count_the_gap_as_time_on_the_microphone,
banshee_is_offered_after_about_two_seconds,
the_site_is_resolved_while_hex_is_in_front,
a_page_seen_minutes_ago_no_longer_names_the_call,
a_remembered_page_belongs_to_its_browser_and_its_call,
finding_the_page_keeps_the_run_toward_the_known_threshold,
a_voice_note_on_another_site_is_not_a_banshee_call,
a_gap_with_the_app_absent_counts_as_absence,
a_recorded_call_that_left_the_microphone_is_not_snoozed_for_another_minute,
a_slow_tab_query_never_holds_up_the_loop,
a_reset_drops_the_answer_in_flight_without_starting_a_second_query,
an_answer_is_dated_by_when_its_query_finished,
a_cold_tab_query_then_its_answer_leads_to_a_banshee_offer and
a_snoozed_or_non_browser_application_is_not_queried (meeting/watcher.rs),
the_meeting_tab_query_reads_only_the_active_tab (dictation/context.rs),
a_browser_voice_note_is_not_offered_but_a_sustained_browser_call_is,
offer_titles_name_the_service_site_or_browser_without_repeating_call,
choices_apply_to_the_site_when_known_and_the_app_otherwise,
always_record_starts_after_the_same_stability_time_as_an_offer, and
never_offer_and_snoozed_calls_never_start in
meeting/detection.rs;
meeting_providers_ask_by_default_and_legacy_never_offer_entries_stay_never in
app_settings.rs; the capsule checks in
meeting_capsules.rs
(always_record_saves_the_choice_and_records_this_call,
never_offer_saves_the_choice_and_dismisses,
a_browser_on_an_unknown_page_cannot_be_set_to_always_record,
an_offer_names_the_call_without_asking_about_consent,
an_automatic_recording_says_so_at_first); and
meetings_settings_save_and_ask_for_system_audio (Linux pane tests). The
controller loop that turns Detection::Record into a recording has no
automated test; it shares the manual Record path.
Sources: meeting/detection.rs,
microphone_activity.rs,
dictation/context.rs, the controller in
meeting/watcher.rs (which logs INFO when an
offer is triggered), and the offer capsule in
meeting_capsules.rs.
Checks: resolves_unregistered_chromium_and_electron_audio_helpers_to_their_host_apps,
resolves_helper_bundle_ids_when_parent_lookup_is_unavailable,
attributes_safari_webkit_gpu_and_facetime_avconferenced_only_when_active,
canonical_bundle_matching_covers_supported_apps_and_variants,
classifies_helper_and_host_microphone_applications,
cleans_google_meet_titles_and_ignores_raw_meet_codes,
switching_tabs_during_a_snoozed_browser_call_does_not_re_offer,
parses_brave_tab_url_and_title_output,
requires_stability_and_offers_once_per_session,
a_brief_microphone_release_does_not_re_offer_the_same_call, and
named_meetings_keep_their_title_and_app_calls_use_the_app.
Observed (2026-10-19): live CoreAudio process inspection on Studio and a headless
Brave WebRTC getUserMedia({audio: true}) reproduction on Pro confirmed
com.brave.Browser.helper and com.tinyspeck.slackmacgap.helper had
NSRunningApplication == nil before parent/bundle resolution and resolved to
com.brave.Browser and com.tinyspeck.slackmacgap afterward.
The capsules have no --snap scene. HEX_CAPSULE_SNAPS=<folder> cargo test --bin hex capsule_snapshots renders the offer, its choices, the
calendar reminders, and the automatic-recording states in light and dark on a
Mac with a GPU.
Meetings > Settings > Calendar // meetings.calendar (macOS)
├── Connect calendar -> macOS full-access prompt, on this click only
│ ├── Granted -> meetings.calendar.connected = true; reminders on, 1 min lead
│ │ └── trusts the prompt's answer: macOS keeps reporting "not determined"
│ │ to the asking process until it relaunches
│ └── Denied / Restricted / write-only -> "Calendar access is off"
│ └── Open settings -> Privacy & Security › Calendars
└── Connected
├── Remind me before meetings -> on by default
├── Remind me -> At start / 1 / 2 / 5 min
├── Calendars -> All calendars, or "2 of 3 calendars"; each switched in the menu
└── Next 3 meetings: title, "Today · 2:30 PM", provider icon when it has a call link
Meeting = not all-day, declined, free, or cancelled, AND has other attendees or a
Zoom / Google Meet / Teams / Slack huddle / Webex link (URL, location, notes)
Lead time reached (or Mac wakes within 5 min of the start) // meetings.reminder
-> Reminder capsule, offer-capsule placement, focus-free
├── "Design sync" · "Starts in 1 min · Zoom"
│ ├── Not now -> close; this call is not offered when detected
│ ├── Join & record (only with a link) -> open the link, then record
│ └── Record -> recording titled "Design sync" with its attendees
└── Service set to Always record: "Starts in 1 min · Hex records automatically"
├── Don't record -> close; the detected call neither offers nor auto-records
└── Join (only with a link) -> open the link; Always record starts on detection
-> Closes 60 s after the start (at least 30 s after showing); withdrawn if the
meeting is cancelled, moved, or reminders are turned off. One at a time: an
overlapping meeting's reminder waits until this one is answered or closes.
Waits while Hex records; a recording that starts closes it.
Detected call during a calendar meeting on the same service
-> recording takes the calendar title and attendeesSettings persist as meetings.calendar (connected, excluded_calendars,
remind, lead_minutes) in settings.json; missing means not connected, so
files from older builds stay off. Every calendar is included unless excluded.
Hex never asks for calendar access at launch: only Connect calendar calls
requestFullAccessToEvents (NSCalendarsFullAccessUsageDescription). With
Meetings off there is no Calendar card, no EventKit read, and no reminder.
The controller thread reads EventKit (one bounded query, 48 hours ahead, at most
200 events) when the store's change notification bumps its counter or once a
minute by the wall clock, so a wake rereads; each loop is then a cheap
scheduler pass. Reminders key each occurrence by event ID and start, so a moved
meeting reminds again and each occurrence reminds once. Settings reads its own
snapshot on a reader thread while the window shows, rereading when the
settings, access, or (once connected) the store change, and every 30 s; the
window's thread never calls EventKit. No network, never on the audio or UI
thread. Recording from a reminder (or dismissing it) snoozes detected calls
from the link's service until the meeting ends; without a link it covers only
the next detected call, and only until 5 min after the start (or the end, if
sooner). The manifest's calendar field and the
Markdown's Attendees line carry the calendar title and attendees, and the notes
prompt gets them as context.
Checks: meetings_need_other_people_or_a_call_link,
all_day_declined_free_and_cancelled_events_are_skipped,
excluded_calendars_are_left_out_and_meetings_sort_by_start,
call_links_are_found_in_the_url_location_or_notes,
other_links_and_lookalikes_are_not_calls,
a_link_after_a_bare_http_in_the_same_word_is_found,
the_url_field_wins_over_the_notes,
an_overlapping_meeting_waits_for_the_showing_reminder,
a_late_reminder_stays_up_at_least_half_a_minute,
a_reminder_shows_once_at_the_lead_time, at_start_reminds_when_the_meeting_begins,
waking_shortly_after_the_start_still_reminds_but_not_much_later,
a_showing_reminder_closes_when_its_meeting_is_cancelled_or_long_started,
a_moved_meeting_is_reminded_at_its_new_time, back_to_back_meetings_each_remind,
reminded_occurrences_are_forgotten_after_they_end,
turning_reminders_off_withdraws_the_showing_one, and
a_detected_call_belongs_to_the_current_meeting_on_its_service in
calendar.rs;
a_call_answered_from_its_calendar_reminder_is_not_offered_again and
a_reminder_without_a_call_link_covers_only_the_next_call in
meeting/detection.rs;
no_reminder_shows_over_a_recording and
a_dismissed_reminder_without_a_link_snoozes_only_around_its_start in
meeting/watcher.rs;
calendar_reminders_stay_off_until_connected_and_survive_older_files in
app_settings.rs;
a_calendar_meeting_gives_its_title_and_attendees_as_context and
markdown_lists_the_calendar_attendees; the reminder capsule checks in
meeting_capsules.rs
(a_reminder_with_a_link_joins_and_records_on_one_click,
a_reminder_without_a_link_only_records,
dismissing_a_reminder_tells_the_controller,
an_always_record_reminder_says_so_and_never_offers_record,
the_reminder_counts_down_to_the_start); and the Linux pane tests
the_calendar_asks_for_access_only_when_connect_is_pressed,
a_connected_calendar_saves_reminders_and_lists_meetings, and
denied_calendar_access_links_to_privacy_settings; the answer checks
a_grant_is_full_access_even_while_the_status_is_stale and
a_refusal_is_a_denial_unless_the_request_failed in
calendar.rs, and
a_granted_calendar_is_saved_connected_and_stays_connected,
a_failed_save_shows_its_error, a_denied_calendar_is_not_saved_and_stays_blocked,
and a_failed_request_keeps_connect_and_shows_the_error in
macos_host.rs. Each step of Connect calendar
logs a calendar: line to process.log. Scenes:
meetings-settings (disconnected), meetings-calendar, and
meetings-calendar-denied.
Not yet observed: the EventKit bridge against a real calendar, the macOS
permission prompt, and a reminder on screen. The controller loop that turns a
reminder click into a recording has no automated test; it shares the manual
Record path. Sources: calendar.rs,
calendar.swift, Reminders in
meeting/watcher.rs, CalendarFeed in
macos_host.rs, and
platform_settings.rs.
Record (offer, menu bar "Record Meeting", Meetings pane, or voice command)
-> Title: named meeting OR "<App> call — 2:30 PM" OR "Meeting — 2:30 PM"
-> system.wav + microphone.wav, owner-only, Application Support/meetings/<id>
-> No idle sleep; no dictation mute or media pause // meetings.record
-> Menu bar: record symbol + elapsed time
├── "Recording · <title> · 12:34" -> Meetings pane
│ └── title follows the provisional title (see Titles And Summary)
└── Stop & Transcribe
(Idle menu bar: "Record Meeting" + "Copy Last Meeting Transcript")
-> Floating recording indicator (when Show recording indicator is on) // meetings.indicator
├── Rune interactive overlay: a non-activating panel that never becomes key
├── In the saved recording_indicator_corner
├── Compact: pulsing red dot · title · mm:ss, plus "+N" when turns wait
├── Hover -> widens toward the screen with the actions below; pointer
│ leaving -> eases back to compact (a held press keeps it open)
├── Drag -> follows the pointer; release -> snaps to the corner nearest
│ its centre and saves recording_indicator_corner (window settings too)
├── Copy new (N) -> copies the turns not yet copied or pasted, through
│ the click (see meetings.copy-through-now)
│ ├── Shares Option-Control-V's cursor: either one advances both
│ ├── N = speaker turns the ticker has seen; always enabled while
│ │ recording, since the latest speech may not be counted yet
│ ├── "Transcribing…" (disabled) while it waits, then copies; "Copied" for 1.5 s
│ └── The wait runs on its own thread, never on the main thread
├── Copy all -> the in-call transcript so far as speaker-turn Markdown;
│ disabled until there is text
│ └── Both read the Parakeet in-call transcript (TranscriptReader) once a
│ second on the ticker thread, never on the main thread
├── Open -> activates Hex, then opens the active meeting in the Meetings pane
└── Stop -> Stop & Transcribe
-> Settings window may stay closed
Detected app leaves the microphone for about 3 s // meetings.call-ended
-> "Zoom left the call" capsule: Keep recording / Stop & transcribe
-> No timeout; nothing stops automatically
Labs › Stop when the call ends (macOS, off by default; #835) // meetings.auto-stop
Only a recording Hex started on its own (Always record); manual, offered,
and calendar recordings are never stopped
-> The call app counts as present while it holds the microphone OR any of
its Core Audio processes plays output (WhatsApp keeps the microphone
while muted; its output stays open until hang-up)
-> Both off for about 3 s -> capsule says "Hex stops recording in 30 s
unless you keep recording."
├── App back on the microphone or output within 30 s -> nothing stops
├── Keep recording -> nothing stops for this absence; leaving again re-arms
├── Stop & transcribe -> stops now
└── 30 s pass -> Stop & Transcribe, as the menu bar's; logged
"meeting recording stopped automatically after its call ended"
-> Off -> exactly as above: microphone only, nothing stops
Capture sources (meeting/capture.rs) // meetings.capture
├── Microphone -> dictation's input (saved device, else System default) via cpal, resampled to 16 kHz
│ ├── System default changes, the Settings microphone changes, or a missing
│ │ saved device returns, mid-meeting
│ │ -> New input opens before the old drops; same track, no retry gap
│ │ // macOS only (meetings are macOS); a failed open keeps the old input
│ └── Saved device listed but would not open -> System default stands in
│ -> tried again after 1, 2, 4, 8, 16, 30, 30, 30 s, then only on a change
└── System audio -> Core Audio process tap (global, excluding Hex) on a private
aggregate device; no display dependency
└── Tap not authorized + Screen Recording granted -> ScreenCaptureKit fallback
A source fails (display sleep ends SCStream, device unplugged, tap stalls 3 s)
-> Only that source stops; the other keeps recording
-> Retried every 0.5-5 s until it reopens or the meeting stops
-> Resumes into the same track; silence fills the gap (>= 1 s) on the
shared capture clock, recorded in the manifest as track `gaps`
-> Rolling transcription restarts that source after the gap; the padded WAV
keeps the final pass on the same timelineStarting a recording no longer opens the Settings window; failures still do.
A failure shows "Meeting could not be recorded." above the recordings until
its close button dismisses it (#562;
check a_meeting_recording_error_can_be_dismissed).
Checks: call_end_is_reported_once_per_sustained_absence,
an_ended_call_stops_after_the_grace_unless_it_comes_back_or_is_kept in
meeting/detection.rs,
only_automatic_recordings_stop_when_the_call_ends_and_only_with_the_lab_on and
keep_recording_disarms_a_pending_automatic_stop in
meeting/watcher.rs,
an_automatic_stop_says_so_and_keep_recording_cancels_it in
meeting_capsules.rs (auto-stop; not
yet observed on a real Mac: the output read
microphone_activity::application_running_output against a live WhatsApp
call, a muted call, and Zoom or Teams helpers),
paste_cursor_counts_coalesced_turns_and_advances_only_on_success in
meeting/tests.rs,
meeting_delta_coalesces_turns_in_time_order in
parakeet.rs,
paste_cursor_neither_repeats_nor_drops_text_when_the_transcript_is_rewritten, and
meeting_menu_offers_one_action_per_state in
macos_rune/status_item.rs, and
mid_meeting_capture_loss_proceeds_to_transcription_when_audio_was_recorded,
writer_fills_a_capture_gap_with_silence_and_records_it, and
a_source_that_resumes_after_an_outage_is_padded_back_onto_the_timeline in
meeting/tests.rs. Menu-bar Record Meeting and
Stop & Transcribe, and the recording and ready capsule buttons, were clicked
on a real Mac on 2026-10-22; no automated test covers them.
The capsules are Rune overlays in meeting_capsules.rs:
interactive, non-activating NSPanels at status level on every Space,
fed by the controller events the menu-bar pump receives
(macos_rune.rs). The offer (20 s), "left the
call", ready (15 s, Copy / Reveal / ✕, notes refresh) and a recording capsule
(title, elapsed time, Copy new, Copy all, Open, Stop, in the configured
corner, compact until hovered, dragged between corners) are ported. Copy new
and Copy all are checked by
the_recording_capsule_copies_the_in_call_transcript and
copy_new_copies_the_transcript_read_through_the_click, and rendered by
capsule_snapshots (recording-empty, -live, -transcribing, -copied,
-open, -left); they have not been clicked on a real Mac. Hover and the corner snap
are checked by the_recording_capsule_rests_compact_and_opens_under_the_pointer,
dragging_the_recording_capsule_moves_it_and_snaps_to_a_corner, and
a_released_capsule_snaps_to_the_corner_nearest_its_centre; neither has been
tried with a real pointer. A "Never offer" or "Always record" choice is saved and
also written into the window's live settings. On 2026-10-22 a signed build on a MacBook Pro
showed the recording capsule (Open opened the meeting while it kept
recording; Stop transcribed) and the ready capsule (Copy copied the
Markdown). Before that day's fix the recording capsule never appeared: it
closed and reopened in one overlay batch, and the hide ran last. The offer,
"left the call", "…" choices, and automatic-recording capsules remain unseen
on screen. The ready and automatic-recording capsules' ✕ (#996) is checked by
dismissing_a_ready_transcript_only_closes_it and
dismissing_an_automatic_recording_never_stops_it, and drawn by
panel_goldens (meeting-capsule-ready-*, -auto-started-*); it has not
been clicked on a real Mac.
While recording // meetings.rolling
-> Each track -> one-second blocks -> bounded queue (about 10 minutes)
-> 16 kHz streaming resampler -> chunker + echo envelope
├── First pause after 6 s (pause segmenter; never under 3 s) -> boundary
├── No pause by 10 s -> hard cut; next chunk repeats its last 2 s
│ (so a chunk is at most 12 s of audio)
└── Silent chunk (no 20 ms frame ≥ -60 dB) -> skipped, no inference
-> Each chunk runs on dictation's loaded model, only while dictation is idle
├── No speech detected (Silero, once installed) -> empty transcript, no
│ inference; coverage still advances
└── A dictation request or live stream came first -> retried once idle
-> Timed words joined word by word at a shared word near each overlap's middle
-> sentences (punctuation or a 600 ms pause)
-> transcript.rolling.ndjson: per-track coverage line, then entries
├── Only settled sentences: wholly before the next seam, so a later chunk
│ never rewrites or retracts a published line
├── You entries publish only once the system track is transcribed past them,
│ or once system capture is over 5 s behind the microphone (stalled)
├── Capture gap -> the track restarts after the gap; nothing is dropped
├── Backlog over 120 s of audio -> oldest chunks skipped, track marked
│ incomplete; rebuilt from its WAV after Stop
└── Model failure -> transcript.rolling.error.txt -> "Live transcript unavailable."
-> Every in-call view reads it: Meetings pane, `hex meetings show`, MCP,
provisional titles (TranscriptReader)
Copy new or Option-Control-V while recording // meetings.copy-through-now
-> The capture writer sends its partial blocks, then the request, in
capture order, so the request covers every sample received
-> The rolling worker answers it before any later audio:
├── Queued chunks as usual (published to the snapshot)
├── Each track's audio not yet in a chunk (no 6 s minimum), into a copy
│ of its transcript: the snapshot and later chunks are unaffected
├── Waits for dictation like every meeting chunk; never a second model
└── The same echo and You-waits-for-Them rules as the snapshot
├── Every sample up to the request, even 100 ms past a hard cut; the
│ system track counts as transcribed through all its audio
-> Each track remembers where the copy ended; its sentence ends there
(between the words whose middles lie either side, as boundaries move
when a later chunk hears more), so the copied part and the rest of it
publish as separate entries and the paste cursor neither repeats nor
drops either. A track rebuilt from its WAV after Stop keeps the cuts
-> A copy pressed as capture ends is still answered; quitting ends the wait
-> Up to 3 s (COPY_TRANSCRIBE_WAIT): usually under 1 s; past that, or with
dictation holding the model, copies the in-call transcript as it is and
logs a warning
-> After Stop, or in another process: the in-call or final transcript
Stop & Transcribe
-> Flush tails -> finish pending chunks // usually seconds
-> Any track that fell behind or failed -> stream its WAV in 1 s blocks
-> Join on one timeline -> Echo suppression -> Final publication
Hex quits while recording // meetings.quit
-> Capture stops; WAVs and manifest finalized; no chunk starts, no model loads
-> Interrupted with its rolling draft + final.pending beside the manifest
-> Next launch, Meetings on, no recording, once the dictation engine is up
(or 30 s without one) -> full-WAV final pass -> Complete + Markdown + notes
├── Quit again or model not installed -> stays pending
└── Other failure -> stays Interrupted with the error and its draftQuitting gives its workers 5 s before _exit, and the final pass of a long
meeting can take longer, or load a model once the dictation engine is gone.
Sources: record, finish_pending in meeting.rs,
PendingFinals in meeting/watcher.rs. Check:
quitting_mid_meeting_loads_no_model_and_finishes_in_time. No repeatable
driver quits a real recording and relaunches.
Design choice: chunks are background jobs on the dictation transcription engine
(TranscriptionEngine::background), using whatever model dictation has loaded,
rather than a second copy of the model (about 0.7 GB). Before each chunk the
meeting waits (up to 20 s per chunk) while parakeet::dictation_busy() reports
a capture, counted from the shortcut press until its clip is submitted, or
dictation inference; the engine thread checks again before running the job. A
job never interrupts a live stream: one that arrives during a stream, or after
a newer dictation request was sent, is turned away and retried 250 ms later,
once dictation is idle. A chunk already running cannot be aborted
(transcribe.cpp ignores its cancel callback on Metal), but it can only have
started before the press, so it finishes during the 300 ms hold threshold and
200 ms release tail (a chunk of at most 12 s takes well under 0.2 s on the
Pro). Gating at
the intentional hold instead let a chunk start just before the threshold; with
the shortest hold that added about 85 ms at p95 on the Pro. The job runs at utility QoS on
the engine thread, which returns to user-interactive afterwards. Apple Speech runs outside the process, so with
Apple Speech selected, and in a process without the engine (the CLI), the
meeting loads its own transcriber as before.
Seams: the two chunks are spliced at a word both heard within 300 ms of the
middle of the overlap (the same word's timing can shift between chunks);
without one, words starting before the middle belong to the earlier chunk.
Repeated words (two to twelve) at the join are removed, and Stop publishes the
words still waiting on a seam. Joining
words rather than sentences keeps a sentence that runs across a hard cut whole;
joining sentences lost its words on one side (10% word error on You lines).
Speechless chunks: models invent text for silence and noise ("Thank you",
"Grazie a tutti", or the vocabulary prompt), and room or keyboard noise passes
the -60 dB silent-chunk check, so every chunk that passes it also goes through
the Silero speech detector used by dictation (see
dictation). A chunk with no speech of at
least 160 ms becomes an empty transcript without inference, in rolling
transcription, the Stop & Transcribe fallback, and meeting echo. In a probe
outside the tree, run on each microphone entry of one 63-minute Italian call,
the detector found speech in 1 of 152 invented entries (a "Grazie a tutti.")
and in 32 of 33 real ones (the miss: a 40 ms "Certo." at a chunk boundary), and
scanned the call in 1.6 s on the CPU. Invented text inside a
chunk that also holds speech is not addressed. Without the detector only the
-60 dB check applies, as before. A Whisper or Qwen3-ASR chunk that returns only
the vocabulary prompt is emptied too (models).
In-call text was a Moonshine draft until 2026-10-22: the pane showed Parakeet
only for time rolling had covered, and Option-Control-V and the GPUI capsule's
Copy new pasted the Moonshine draft alone, which garbled names and jargon. The
meeting now loads no Moonshine; short Parakeet chunks replace it. Always-on
streaming Parakeet was rejected because one loaded model cannot serve it:
transcribe-cpp (0.2.4, and still 0.4.1) allows one active stream per model
across all sessions, and refuses any other run or stream with Busy while it is open
(Session::stream). Two tracks would need a mixed track (losing You/Them and
echo suppression) or a model copy per track (about 0.7 GB each), and every
dictation would have to close the meeting stream and lose its 5.6 s left
context. The buffered stream also re-encodes a 7.7 s window (5.6 s left,
1.04 s chunk, 1.04 s right) per 1.04 s step, where chunks encode each second
about once: Studio's 1,619 dictation streams of 3 s or longer (3.2 h of audio,
2026-10-23 log) spent 44 ms of feed time per second of audio, which for two
tracks would hold the engine about 9% of the time.
Cost: observed 2026-10-22 on the Pro with meeting_live_replay: 10 minutes of
a recorded speaker-mode call fed at real time to the production recorder beside
the warm dictation engine (Parakeet unified English), with a 4 s dictation every
30 s. It feeds packets directly, not through capture. Word error is against the
final transcript the earlier 30 s chunks produced.
Moonshine draft + Parakeet only,
30 s Parakeet chunks 3-12 s chunks
Meeting CPU 105% of a core 4.4%
Footprint, idle ~830 MB mean 1345, peak 1438 mean 854, peak 869 MB
Dictation release -> text p50 80, p95 93 ms p50 84, p95 89 ms
Speech end -> copyable p50 16.5, p95 28.7 s p50 6.3, p95 11.4 s
(Parakeet; the draft showed in about 1 s)
Option-Control-V text Moonshine, 17% WER Parakeet, 5.6% mid-call
Pasted vs final, Them/You 16.7% / 14.9% 0.0% / 0.0%, no repeats
Final transcript after flush 181 ms after Stop, 3.7% WERDictation latency stays within run-to-run spread (earlier Parakeet-only runs measured p50 87-92 ms, p95 103-104 ms).
Call on speakers -> the microphone hears the remote side tens of ms later
Each microphone segment // meetings.echo
├── Signal (meeting/echo): 20 ms energy of both tracks on one timeline
│ ├── Lag (-300..+600 ms) and coupling from envelope correlation over ±60 s,
│ │ cached per 10 s block once its audio is complete
│ │ └── Correlation < 0.2 (headphones) -> every sound is local
│ ├── Bleed gain = 35th percentile of mic − delayed system, before or after
│ └── Frame is local when mic > predicted bleed (decaying reverb) + 9 dB
│ ├── ≥ 50% local -> Local -> kept, even with matching words (double-talk)
│ ├── ≤ 20% local and no 0.5 s of local sound within 1 s -> Bleed -> dropped
│ └── otherwise -> decided by words
└── Words: ≥ 60% match Them speech within ±1.5 s (60% edit similarity) -> echo
Rolling and final: segments are sentences, grouped into utterances
└── An echo utterance keeps its sentences of 3+ words that the signal shows local
Applied in: rolling snapshot (so every in-call view) and the final transcriptDropped counts are saved as echo_suppressed_utterances in the manifest.
Root causes of You twins in Kit's 2026-10-16 call (laptop speakers, built-in
microphone, Pro under load):
- The live worker's bounded queue dropped 10 ms microphone packets under CPU
load, and gaps under 20 ms of arrival time were not counted. The draft's
microphone timeline drifted up to 6 s ahead of the system track over 18
minutes, so the echo envelope compared unrelated audio and bleed read as
Local(84 lines) or undecided (70). The echoedYouline appeared before itsThemtwin. Packets now carry their WAV sample position. - The rolling snapshot had no coverage, so the draft took over after the last
kept
Youentry (616 s) even though rolling had judged that audio as echo. - A rolling
Youentry could be published before the system chunk that explained it.
Observed with an opt-in replay of that recording through every layer
(meeting_echo_replay, Mac Studio), before the Moonshine draft was removed
(the draft rows no longer apply). Echo-like = at least 60% of the words occur
in remote speech within 6 s. Six utterances where Kit really spoke were
labeled by hand.
Pane as recorded (old code) 77 You entries, 49 echo-like
Draft only (rolling unavailable) 11 You, 2 echo-like, 2 of 6 local lost*
Pane, rolling caught up 10 You, 1 echo-like, 0 of 6 lost
Pane while recording, rolling 25-300 s behind: 25 ever shown, 3 echo-like
Final transcript 10 You, 1 echo-like, 0 of 6 lost
* Moonshine lines that mix bleed with Kit's sentence stay hidden until
rolling, which splits them into sentences, covers that time.Acoustic echo cancellation (Voice Processing IO) was evaluated, not adopted: it replaces ScreenCaptureKit's raw microphone with an AVAudioEngine/VPIO input, ducks other audio, moves Bluetooth headsets to the call profile, adds gain and noise processing to the transcribed track, runs beside the call app's own voice processor, and loses ScreenCaptureKit's shared clock. See ROADMAP.md.
Sources: meeting/transcript.rs,
meeting/echo.rs,
StreamingResampler in dictation.rs. Echo checks:
speaker_bleed_is_classified_as_bleed, talking_over_the_remote_side_is_local,
speech_during_remote_silence_is_local, headphones_make_every_microphone_sound_local,
late_muffled_bleed_is_bleed_and_speech_over_it_is_local,
a_short_phrase_inside_a_long_bleed_segment_is_not_bleed,
the_signal_overrides_word_matching_both_ways,
synthetic_speaker_bleed_is_dropped_and_double_talk_kept,
a_local_sentence_inside_an_echo_utterance_is_kept,
microphone_entries_wait_until_the_system_track_covers_them, and
timed_words_become_sentences_at_punctuation_and_pauses (synthetic signals).
Other checks:
continuous_speech_is_hard_cut_with_overlap_and_covers_every_sample,
chunks_end_at_the_first_pause_after_the_target_length,
short_recordings_become_one_chunk_and_silence_tails_are_dropped,
overlapping_chunks_join_at_the_middle_of_the_overlap, seam_drops_repeated_words,
speechless_chunks_skip_the_model_and_still_advance_coverage,
a_speechless_chunk_after_an_overlap_keeps_earlier_entries,
a_sentence_across_a_hard_cut_keeps_every_word,
rolling_publishes_only_entries_a_later_seam_cannot_replace,
a_capture_gap_restarts_the_track_after_it_instead_of_dropping_it,
a_copy_includes_speech_up_to_the_click,
repeated_copies_neither_repeat_nor_drop_words_as_later_chunks_overlap_them,
repeated_copies_cut_tracks_that_start_at_different_capture_times,
a_copy_just_after_a_hard_cut_keeps_you_while_them_is_silent,
a_copy_cut_holds_when_a_later_chunk_moves_the_words_slightly,
a_track_rebuilt_from_its_wav_after_stop_keeps_the_copies_cuts,
a_copy_waiting_when_capture_ends_is_still_answered,
a_copy_stops_waiting_when_hex_quits,
a_copy_that_runs_out_of_time_gets_no_reply,
a_copy_waits_out_dictation_and_a_preempted_chunk,
a_copy_reaches_only_the_recording_this_process_runs,
the_feed_forwards_a_copy_after_the_audio_before_it,
a_backlog_skips_the_oldest_audio_and_marks_the_track_for_rebuilding,
silent_chunks_are_not_transcribed,
speaker_echo_of_remote_speech_is_dropped, word_level_echo_is_dropped_as_one_utterance,
distinct_or_distant_local_speech_is_kept,
discontinuous_packets_are_placed_on_the_timeline, and
streaming_resampler_matches_whole_buffer_conversion. They use synthetic audio
and transcripts, not model inference or real speaker echo.
Opt-in measurements (ignored tests; they need a private recording and are never
part of CI): meeting_echo_replay (every layer, cached transcripts, hand
labels), moonshine_command_update_latency, and dictation_latency in
meeting/echo_replay_tests.rs, and
meeting_live_replay in
meeting/live_replay_tests.rs: the
production recorder fed a recording at real time beside the warm dictation
engine, with a dictation every 30 s, reporting CPU, footprint, dictation
latency, speech-to-copyable lag, mid-call Copy all and Option-Control-V text
against the final transcript.
Final publication // meetings.output
├── Internal: transcript.ndjson + transcript.md (atomic, owner-only)
└── Markdown copy -> <folder>/<YYYY-MM-DD HHMM> <title>.md
├── Title, date, duration, app, You / Them turns
├── Never overwrites; adds " (2)"
└── Failure -> Meeting still Complete; "Markdown not saved: …"
Transcript ready capsule (15 s) -> Copy (Markdown or speaker turns fallback) / Reveal / ✕ closes
Meetings pane -> Copy icon on a completed row's hover, the card's Copy transcript icon, Reveal Markdown (or Reveal Files when none)
Menu bar (idle) -> Copy Last Meeting Transcript
Option-Control-V -> `MeetingPasteCursor` in `meeting/delta.rs` over the transcript
│ through the press (meetings.copy-through-now)
├── Pastes turns added since the last successful paste
├── Runs in order with dictation output: a dictation finished during its
│ wait (at most 3 s) pastes after it
├── Remembers, per source, the capture time spans it pasted (spans within 1.5 s
│ merge); an entry is new when its midpoint is outside them, so nothing
│ repeats or drops when the final transcript replaces rolling after Stop, and
│ text the final pass recovers for audio rolling skipped still pastes
└── Resets when Hex restartsHeader: Start recording (the pane's one Primary button) / red dot, elapsed
time, and Stop & transcribe (Secondary), grouped at the right
List (on the title's edge, no divider; grouped Today / Yesterday / date)
├── Search meetings (title, app, notes, final transcript) above the rows
└── Row: title (generated when present), time on the right; meta line
"Recording · Zoom" / "Failed · 2 min" / "Zoom · 38 min" (red while
recording or failed); no hover fill; a completed row shows a Copy
icon in the time's place on hover (pointer only; "Copied" as a check)
Detail (a raised card beside the list)
├── Title, status chip (not when Ready), date · time · duration · app
├── Ghost icons top right: Copy transcript, Rename (finished only), "…" menu
│ └── Copy summary (stays open to show "Copied"), Reveal Markdown, Summarize /
│ Regenerate summary ("Summarizing…" disabled while running), separator,
│ Delete… (finished meetings only for the last three)
├── Errors at the top of the scroll area
├── Summary: one paragraph, at most two sentences
├── Chapters (when present): start, name, line, and a Copy section icon
└── Transcript: stacked turns, no bubbles; "You" in text colour, "Them"
faint, each with its clock; merged turns; 30 s+ pause lines;
"Listening…" while recording
Empty: "No meetings yet." with a one-line hint; "No meetings match." while
searching
Rename -> inline field; Enter or Save // meetings.rename
-> manifest title; Markdown heading only while it reads the old title
-> file name unchanged; empty title refused
Delete… (overflow menu) -> "Trash recording & Markdown" (or "Trash recording")
/ Cancel, under the title in place of the icons until answered
-> exported Markdown, then Application Support/meetings/<id>, to the Trash
-> refused while recording, transcribing, or writing notes // meetings.deleteChoice: Delete trashes the Markdown copy too, since it holds the transcript;
both stay recoverable from the Trash. Sources:
rune_ui/meetings.rs, the requests in
rune_ui/macos_host.rs, and trash /
rename in meeting.rs. Checks:
deleting_trashes_the_markdown_then_the_recording_and_refuses_while_recording,
renaming_updates_the_manifest_and_an_unedited_markdown_heading,
retitling_replaces_only_a_matching_first_heading, and the Rune pane tests
meetings_select_search_and_copy_a_transcript,
meetings_rename_from_the_title_field,
deleting_a_meeting_takes_the_menu_then_a_confirmation, and
the_overflow_menu_copies_the_summary_and_asks_for_new_notes.
Scenes: meetings, meetings-recording, meetings-actions,
meetings-delete, meetings-rename, meetings-failed, meetings-empty.
Checks: markdown_lists_metadata_and_labeled_turns and
export_never_overwrites_and_uses_safe_names.
Meeting data is a liability, so new meetings are kept 24 hours by default.
Meetings › Settings -> Keep meetings: 24 hours / 7 days / 30 days / Forever
│ `meetings.retention` day|week|month|forever, or none (unchosen)
├── Unchosen (default) -> meetings recorded since the default began
│ (manifest `retention_applies`) are kept 24 hours; older ones stay
│ until the user chooses (the `meeting-retention-default` migration
│ unsets the `forever` that #604 saved as its default)
└── Chosen -> applies to every finished meeting, older ones included
Each finished card -> "Deleted after 24 hours" (or 7 days, 30 days)
Meeting controller, Meetings on or off // meetings.retention
├── At launch, hourly, and soon after the setting changes
├── Age from ended_at_ms, else created_at_ms; older than its retention
│ -> the recording folder (audio, transcripts, notes and summary, live
│ drafts) to the Trash, never removed outright
│ -> the exported Markdown to the Trash only while its SHA-256 still
│ matches the copy Hex last wrote (manifest `export_sha256`; Hex's own
│ heading and notes rewrites keep it current); an edited copy stays
├── Skips recording, transcribing, writing-notes, and final.pending
│ meetings; a later pass retries them
└── Nothing expires while Hex is not running
Queries (`hex meetings`, `hex mcp`, the pane) -> leave out expired meetings
at once, before a pass moves them; a process that never loaded settings
reads `meetings.retention` from settings.json without writing itSources: retention_for, expired, expire, and trash_expired in
meeting.rs, MeetingExpiry in
meeting/watcher.rs, Library::scan in
meeting/query.rs, the row in
rune_ui/platform_settings.rs.
Checks: retention_expires_meetings_by_when_they_ended_and_skips_active_ones,
until_one_is_chosen_only_meetings_recorded_since_the_default_expire,
expiry_leaves_a_markdown_copy_the_user_edited, and
hex_rewriting_its_markdown_keeps_it_hexs_and_a_user_edit_does_not. No
live run of an expiry pass against a real Trash has been observed.
While recording, setting on, model available // meetings.title.provisional
-> meeting-title thread, utility QoS; checks the transcript every 10 s
(rolling chunks, echo-filtered)
-> ≥ 90 s of speech (or ≥ 600 words; ≥ 60 words either way)
-> waits (≤30 s) while dictation is busy
-> ONE title-only call over the transcript so far (≤5,000 chars, 30 s timeout)
-> Recorder stores provisional_title in the manifest
-> menu bar "Recording · <title>", Meetings pane list and detail
-> Refreshed once when speech reaches 10 minutes; a failure retries a minute
later; at most 3 calls per meeting; Stop discards a call in flight
-> The exported Markdown file name and heading use it when it arrived first
Final publication complete // meetings.notes
-> meeting-notes thread, utility QoS; waits (≤30 s) while dictation is busy
-> ONE call over a bounded excerpt, no map-reduce
├── Lines "[mm:ss] You|Them: text" (long turns split at 600 chars)
├── Whole transcript when it fits; otherwise opening 30 %, up to six
│ evenly spaced middle passages, ending 20 %, "[…]" between them
├── Budget = min(12,000 chars, (context − 1,000 tokens) × 3 chars)
└── Context exceeded -> retried once with half the excerpt
-> 90 s total deadline; the call ≤60 s
-> Manifest: notes { title ≤8 words, summary ≤2 sentences / 400 chars,
excerpt_chars, transcript_chars }
-> Markdown copy, same file name, atomic replace
├── Heading -> final title, only while it still reads Hex's last title
├── <!-- hex:notes --> ## Summary (one paragraph) above ## Transcript
├── Text outside the block is preserved; changed mid-write -> not written
└── Missing file -> manifest only
-> Failure / timeout -> notes_error; Markdown untouched; recording stays Complete
Unavailable (not eligible / Apple Intelligence off / model not ready / macOS < 26)
-> Settings row says why; nothing runs
Meetings pane -> title in list and detail; Summary paragraph above the transcript;
"Summarize" / "Regenerate summary" / "Summarizing…" in the overflow menu
Transcript ready capsule -> "Ready · <title>" once a provisional or final title
exists; subtitle "Summarizing with Apple Intelligence…", then the summaryTitle rule: the shown title is the user's title unless it is still the default
<App> call — 2:30 PM / Meeting — 2:30 PM; then the final notes title, else
the provisional title, else the default. Named or renamed meetings keep their
name. The file is never renamed, so links, open editors, and Reveal keep working.
Action items and decisions are gone: other agents read the transcript for details (MCP). Older manifests still decode: a list summary is joined into one paragraph, and action items, decisions, and chunk counts are ignored (and dropped when that manifest is next written). Their Markdown copies keep their old notes block until regenerated.
Sources: meeting/notes.rs,
apple_intelligence.rs, and the
FoundationModels bridge apple_intelligence.swift
(GeneratedNotes title + summary, GeneratedTitle title only), weak-linked from
build.rs; the recorder loop in record in
meeting.rs. Checks in meeting::notes::tests (fake
model): a_short_transcript_is_sent_whole_in_one_call,
long_meetings_are_excerpted_from_the_opening_middle_and_ending,
context_overflow_halves_the_excerpt_once_and_failures_stop,
titles_are_requested_after_the_opening_then_once_at_ten_minutes,
provisional_titles_use_the_title_prompt_over_the_transcript_so_far,
generated_and_provisional_titles_replace_only_default_titles,
older_notes_with_points_action_items_and_decisions_still_read,
notes_are_inserted_above_the_transcript_and_regenerate_idempotently, and
user_edits_outside_the_notes_block_are_preserved; menu text in
meeting_menu_offers_one_action_per_state. The recorder thread, manifest write,
and menu/pane refresh during a real recording are unexercised.
Real model (debug CLI): hex meeting summarize <file.md> [--excerpt-chars N]
times the provisional title at the point a recording would ask for it, then the
final title and summary, without saving; hex meeting summarize <id> writes
them like Regenerate.
Observed (2026-10-15, Mac Studio M2 Max, macOS 27.0.1, context 8,192 tokens, debug build) on a synthetic 50-minute, 7,700-word transcript (206 turns, 46,000 chars):
Provisional title at 01:41 (261 words, 101 s of speech) 0.7 s (1.0 s first call)
Final title + summary, one call, 11,151-char excerpt 3.4–3.5 s (3 runs)
└── budget 9,000 -> 2.6–3.4 s; 18,000 -> 5.7 s
Before: map-reduce over 8 chunks, 9 calls, 51-minute call 96 sA Labs toggle, off by default: Live chapters
(labs.live_chapters, read when a recording starts). Off, nothing below starts, and meetings behave as without it.
Recording starts, toggle on // meetings.chapters.live
-> meeting-chapters thread, utility QoS; checks the rolling transcript every 5 s
(nothing read while Apple Intelligence is unavailable or titles are off)
-> ≥ 3 min of new meeting time and ≥ 40 new words -> waits (≤30 s) for dictation
-> ONE call over only the new lines (≤3,600 chars, newest kept, "[…]" before)
├── Prompt: vocabulary terms (≤30, vocabulary experiment) -> new lines ->
│ "Current chapter: X"
└── Answer: a 2–5 word name, one line, and "same topic or not"
-> Rust decides, not the model's flag alone
├── First name -> chapter 1 at 00:00
├── Name sharing > half its words with this chapter's last 3 names, or any
│ word when the model says "same" -> stays (clears a pending departure)
├── Otherwise a departure; it opens a chapter, dated at its window's first
│ line, only when the next pass departs too and the current chapter has
│ lasted ≥ 90 s. A second departure naming yet another topic waits for
│ its own confirmation
└── Refused passage -> counted as read; failure -> retry after 1, 2 … 5 min
-> Recorder stores chapters in the manifest -> title, menu bar, pane
Stop
-> A departure still waiting for its second pass opens (≥ 90 s rule applies)
-> A pass finishing after Stop is discarded
After final publication, inside the notes thread // meetings.chapters.refine
-> One call per boundary, all within 30 s: lines (not merged turns) within
3 min of the live boundary, "Chapter before/after: name (line)"
-> Model lists the L numbers about the chapter after; Rust moves the boundary
to the split that disagrees with the fewest labels, only if the labels
cover at least half the lines after the live boundary and the new start
stays after the previous chapter's
-> chapters_refined = true; a failed call keeps its boundary
-> Each call first waits (≤30 s) for dictation; a stop or quit ends the pass
with nothing saved, so the next notes run redoes it
Copy section (pane, per chapter; menu bar "Copy Section" while recording;
`hex meetings show --chapter N`)
-> "## <name>\n\n<line>\n\n" + the transcript lines that start inside the
chapter, joined into turns only within it (one shared function)Titles: with Live chapters on, the manifest records title_source (default,
call, calendar, user); off, it is written only to a manifest that already
has it or has chapters. Unless it is user, the shown title is the base title
plus up to three of the longest chapters in meeting order, once there are two:
"Team sync: image storage, motion lint, chat app name" (≤100 chars; a name that
would pass that is left out). While recording, the last chapter runs until now.
A title the user typed, including a rename while recording or transcribing, is
never extended. Manifests without the field read as user when their title is
not the default.
Read surfaces: hex meetings chapters <id> [--json], hex meetings show <id> --chapter N, a ## Chapters list in show, chapters in show --json
(JSON stays version 1), and MCP get_chapters.
Sources: meeting/chapters.rs (worker, decisions,
boundary pass, title), GeneratedChapter / GeneratedChapterLines in
apple_intelligence.swift, the record loop
and TitleSource in meeting.rs. Checks in
meeting::chapters::tests (fake model): pass plan and back-off, first chapter,
two-passes-away, minimum length, name overlap and the model's flag, refusals,
prompt order, pass window, confirming on another topic, Stop opening a waiting
departure, the boundary pass (one call per boundary, unsupported answers kept,
partial failures, a stopped pass saving nothing), title building and the
recording title, section Markdown, and the worker;
meeting::tests::chapters_extend_every_title_but_one_the_user_typed;
copy_section_matches_the_menu_bar_and_the_cli (macOS host: pane, menu bar,
and CLI give the same section when one speaker's turn crosses a boundary);
copy_section_copies_one_chapter (Linux-only Rune tests). The menu bar
submenu, the recorder writing chapters during a real recording, and the
meetings-chapters scene on a Mac screen are unexercised.
Real model (debug CLI): hex meeting chapters <file.md> runs the live passes
as a recording would, then the boundary pass, without saving.
Observed (2026-10-23, Mac mini, debug build) on a synthetic 15-minute, three topic transcript (true changes at 05:32 and 11:02), 5 runs: passes 1.0–2.4 s; boundary pass 1.8–3.4 s (2–3 calls, ~1,500 prompt chars each). All runs found all three topics; 2 of 5 added a spurious "cdn cache headers" chapter at 03:42. The second change landed at 11:02 in 3 runs and one line late (11:24) in 2; the first at 05:32 in 2 runs and stayed at the live 06:38 in 3. The model's same-topic flag was close to random ("same" for unrelated names, "new" for the current one), which is why Rust's name overlap decides.
The release CLI also supports hex meetings list, show <id|latest> (with
--from/--to offsets or --chapter N), chapters <id>, and search <query>
through this query layer. See the transcript CLI map
and versioned JSON contract.
hex mcp [--meetings-dir <path>] // meetings.mcp; release builds
├── MCP over stdio; independent of the Meetings opt-in (read-only)
├── Dispatches before process logging, the instance lock, GUI, and permissions
│ └── Safe beside the running app; logs only to stderr (HEX_MCP_LOG)
├── Default folder: Application Support/hex/meetings (hex on older builds)
│ └── --meetings-dir -> any mirrored copy (rsync of that folder)
├── A copy named hex-meetings-mcp -> always `hex mcp` with the same flags
│ (no subcommand never falls back to listening)
└── Tools (all readOnlyHint)
├── list_meetings(since?, until?, query?, limit?, include_in_progress?)
│ └── id · title (generated when present) · ISO start · mm:ss · status ·
│ transcript kind · participants "You, Them (<app>)" · notes yes/no
├── search_transcripts(query, since?, until?, meeting_id?, limit?, fuzzy?)
│ └── per-meeting counts + ranked passages: id, title, speaker,
│ mm:ss @ ISO time, snippet with **matches**, before/after lines
├── get_transcript(meeting_id, start?, end?, speaker?, max_chars?, cursor?)
│ ├── merged You/Them turns "[mm:ss · HH:MM:SS] Them: …" + next_cursor
│ └── start/end, or the same as from/to (own schema fields; not both):
│ entries overlapping the range; a start not before the end (an
│ omitted start is 0) or past the meeting's end is an error
├── get_meeting_notes(meeting_id)
│ └── stored title + two-sentence summary + "read the transcript for
│ details, decisions, and action items", or an explicit
│ "No Apple Intelligence notes are stored" + get_transcript hint
└── get_chapters(meeting_id) // Labs
└── "N. mm:ss–mm:ss · name" + line each, whether boundaries were
corrected, a get_transcript start/end hint; or "No chapters are
stored" ("No chapters yet" while recording); never generates any
Resources: hex-meeting://<id> -> Markdown (metadata, notes, transcript)Read-only and private: the server opens files for reading only, never writes,
repairs, or recovers anything in the meetings folder (unlike meeting::list,
which persists recovered statuses), creates no index or cache on disk, runs no
model, and makes no network request. It never reads the exported Markdown in
~/Documents, so SSH sessions need no Documents access. Transcripts leave the
Mac only through whatever transport the MCP client uses (stdio, or SSH).
Concurrency: a recorder holds active.lock; the server probes it with a
read-only, non-blocking shared flock and releases it immediately. Held ->
recording (in progress) with the rolling transcript (echo-filtered), labeled
provisional. Not held ->
the app's recovery rules apply without writing: published transcript.ndjson
is final, an unfinished draft is interrupted. Stale lock files from finished
recordings read as not held. A mirror cannot see the Pro's lock, so a meeting
still recording there appears interrupted with its rolling transcript so far. Unreadable
manifests are listed as skipped folders; unreadable NDJSON lines are skipped and
counted; an unterminated last line is treated as a write in progress.
Search: in-memory, rebuilt per meeting when its files' sizes or times change.
Passages are same-speaker runs of up to 60 words (3 s turn gap) plus one per
stored notes block. Text is NFKD-folded (case and diacritics), tokenized, and
lightly stemmed (scheduled/scheduling -> schedul). BM25 (k1 1.2, b 0.75)
over expanded terms: exact 1.0, prefix 0.5, edit distance 1 (2 from 8 letters)
0.35, Soundex 0.2 for 3-5 letter words (Dacks -> Dax); partial-term
coverage weighted the same way, and adjacent-term bonuses. Passages matching
every term exactly rank above all others. Edit and Soundex fallbacks apply only
to a term with fewer than three exact passages, and skip words in more than
0.5% of the passages searched (at least five) unless the term has no exact hit
and the word is exactly one edit away. This keeps made, blog, Bob, and
believe out of a media/blob search once those words appear exactly in
three passages, while a typo of a rare word still finds it. A term's match in a
passage is its exact stem when present, then the best score, kind, and
alphabetically first stem, so ties are deterministic. "Quoted words" are
required exact (stemmed) phrases; fuzzy: false keeps only exact stems.
hex history --search shares this ranker, counting an entry's raw and final
text as one document.
Semantic search is not shipped. On-device candidates are Apple NaturalLanguage
NLContextualEmbedding (asset download, macOS 14+) or the older static
NLEmbedding sentence model, through a Swift bridge like apple_speech, with a
cache under ~/Library/Caches/hex/meeting-index keyed by meeting
fingerprints. Full-text with stemming and fuzzy matching answered the real
queries below; embeddings wait until a query fails for lack of paraphrase.
Sources: meeting/query.rs (meeting::query,
queries and rendering) and meeting/mcp.rs (rmcp
3.5 adapter); run_mcp in main.rs. Checks (synthetic
fixtures in tests/fixtures/meetings and tests/fixtures/meetings-ranking):
meeting::query::tests::* (listing and skipped folders, filters, misspelling
tolerance and ranking, stemming, accents, required phrases, context, drafts,
cursor paging, notes, held lock, queries_never_write_to_the_meetings_folder,
time and strict offset parsing, offset ranges on final, rolling, and
in-progress transcripts (including the "so far" error),
exact_stems_outrank_loose_matches_to_common_words,
passages_matching_every_term_exactly_rank_first,
an_all_exact_passage_outranks_a_higher_scoring_partial_one,
a_term_found_in_fewer_passages_still_reaches_its_neighbours,
a_misspelled_rare_word_still_finds_its_passage, and
spelling_fallbacks_need_rare_terms_and_uncommon_candidates) and
tests/meetings_mcp.rs (initialize with protocol 2025-06-18, tools/list with
schemas (including from/to) and read-only annotations, tools/call including
from/to ranges beside null start/end and their errors, resources/read,
stdout carries only JSON-RPC, no Application Support state created).
Observed (2026-10-23, Mac Studio, debug build, live meetings folder, read-only):
hex meetings search "images database blob storage media" dropped from 315 to
140 matching passages, with no fuzzy-only hit in the top 25 (before: four,
through blog, blow, believe, made, and motto); the top hit remains the
in-progress meeting's 115:02 passage, and 6 of the top 10 fall in its
113:03–120:43 storage discussion. show <id> --from 113:03 --to 120:43 returned
that section's 168 rolling entries as Markdown and JSON.
Observed (2026-10-15, Mac Studio, release build, read-only copy of the Pro's 8
meetings without WAVs): first launch of a freshly signed binary 440 ms to
initialize (Gatekeeper), then 8 ms; list_meetings 4-7 ms cold; searches
0.5-1.2 ms; a 51-minute get_transcript 0.5 ms; resources/read 0.6 ms.
Don't: MCP client config runs `ssh pro hex mcp` // one SSH per client
-> 41 OpenCode instances = 41 SSH sessions -> the Pro's sshd reset connections
Do: one periodic pull, then local servers // meetings.mcp.mirror
scripts/sync-meetings-mirror.sh (LaunchAgent template, every 120 s,
ProcessType Background, Nice 10, LowPriorityIO)
├── ONE rsync over ssh (BatchMode, ConnectTimeout 5, --timeout 60)
│ pro:Library/Application Support/hex/meetings/
│ -> ~/Library/Caches/hex-meetings-mirror/ (0700)
├── Skips *.wav, *.lock, *.tmp; --delay-updates (files land together at the
│ end); --delete-delay (meetings trashed on the Pro disappear)
└── Pro asleep / unreachable -> exit 0 silently; next run retries
Each MCP client -> local `hex mcp --meetings-dir <mirror>` (no SSH, no lock)
└── No lock in the mirror -> a meeting still recording on the Pro reads as
`interrupted` with its rolling transcript so far; final once publishedTemplate: hex-meetings-mirror.plist (placeholders for the checkout and home; not installed automatically).
Observed (2026-10-15, Studio pulling from the Pro): one sync 0.44 s, 8 meetings,
1.0 MB, no WAVs or locks; unreachable host exits 0 at once, unanswered address
exits 0 after the 5 s connect timeout. hex-meetings-mcp --meetings-dir (release
build in ~/.local/bin) over stdio: first launch of the new binary 378 ms to
initialize (Gatekeeper), then 7 ms; list_meetings 3.5–11 ms cold, 0.5 ms
warm; searches 0.6–1.5 ms; a 48,000-char get_transcript 0.6 ms;
get_meeting_notes ≤0.3 ms, including an older manifest with action items;
resources/read 0.5 ms. 40 parallel instances: all initialized (median 13 ms,
max 22 ms), listed, and exited 0 in 76 ms wall. The LaunchAgent is not loaded,
so ssh-agent access from launchd is unverified.
Granola import: see granola-import.md.
- No executed end-to-end recording with a real call, Screen Recording grant, or speakers echo in this change; see the test script in the handoff.
- The process tap, its System Audio Recording prompt, and display-sleep
recovery have not run in a recorded meeting. TCC status comes from the
private
TCCAccessPreflight; a denied tap would otherwise record silence. - Microphone and system audio now run on separate device clocks aligned by arrival time; drift below the 1 s gap threshold is uncorrected and echo thresholds were tuned on ScreenCaptureKit's shared clock.
- Calendar titles (EventKit) are not implemented.
- In-call text trails speech by one chunk plus its settling (seconds, see the replay numbers); nothing shows a partial sentence before then. A track that falls more than 120 s behind skips audio until Stop rebuilds it.
- The recording capsule's Copy new / Copy all are unverified on a real Mac screen; its count can trail the transcript by up to a second.
- Copying through the click is checked with a fake model only; its real-Mac
latency and how often the 3 s wait runs out are unmeasured. Handing a
copy's cuts from the rolling worker to the WAV rebuild in
transcribehas no test of its own; the rebuild with cuts does. The copy waits for the next audio packet to arrive, so with both sources stopped it runs out of time and copies the in-call transcript. - The Meetings pane is verified by Rune goldens rendered offscreen (on Linux and on hailmary's Metal), not on a Mac screen; the capsules have no golden.
- Echo thresholds are tuned on two speaker-mode calls (2026-10-15 and 2026-10-16), with six hand-labeled local utterances; other rooms, external speakers, and Bluetooth are unmeasured. The 2026-10-16 replay audio was lost with Studio's temporary directory, so those numbers cannot be re-run. Real NSFileManager trashing and the native rename field are unexercised in the app.
- CPU, memory, and latency numbers come from the replay harness on the Pro, not a recording in the app with real capture and hotkey dictations.
- The short-chunk rolling transcript has not run in a real call yet.
- Why the rolling worker stalled for over a minute on the Pro is unknown; slow chunks (> 5 s) are now logged.
- Titles and summaries have not run after a real recording in the app; the CLI path exercised the real model, and the provisional-title thread, its manifest write, and the menu/pane refresh are unexercised in a live recording.
- Live chapters (Labs) have not run in a real recording: the worker, manifest writes, title updates, menu bar Copy Section, and the boundary pass after publication ran only in unit tests and the debug CLI over one synthetic transcript. The thresholds (3 min passes, 90 s minimum, name overlap) are tuned on that transcript; the model's same-topic flag is unreliable, and a short detour can still become its own chapter. The boundary pass runs only when meeting notes run, after publication.