Meetings
When to use
Reach for this skill any time the user asks about a meeting, calendar event, or attendee-tagged transcript. Specifically:
- Listing upcoming/past meetings (
/meetings). - Opening a single meeting detail with transcript + AI notes (
/meetings/:id). - Generating notes (summary + bullets + action items) for a finished meeting.
- Connecting Google Calendar (and later iCloud).
- Reasoning about who said what when system + mic audio are both captured.
For press-and-hold dictations (Hold-Fn / Cmd+Shift+Space) and the /dictate tab, use the dictate skill.
Design reference
The Meetings tab intentionally mirrors Granola: a compact "Coming up" card over a dense reverse-chronological history, two-pane detail (transcript left + AI notes right), inline title edit, "Generate notes" button, per-attendee action items. See templates/clips/desktop/design-refs/granola-ux.md for the source-of-truth interaction notes — read this before redesigning any Meetings surface. Dictation behavior belongs in the Dictate skill.
The list was a grid of tiles until 2026-08-14. That contradicted §2 of the ref ("list-row style rather than tile cards") and cost so much vertical space that history sat below the fold, which is how a user ends up unable to find last month's call.
Data model touched
meetings— title, scheduled/actual start+end, platform, joinUrl, recordingId, transcriptStatus, summaryMd, bulletsJson, actionItemsJson, source, ownableColumns.meeting_participants— meetingId + email + name + isOrganizer + attendedAt.meeting_action_items— meetingId, assigneeEmail, text, dueDate, completedAt.calendar_accounts— provider, externalAccountId, secret refs, lastSyncedAt. (See onboarding-calendar plugin.)calendar_events— compatibility snapshot for events that have been recorded or edited; the visible list reads Google Calendar live.recordings— when a meeting is recorded, the resulting recording row carriesmeeting_id(non-null) so we keep a bidirectional link. See therecordingskill for the inverse direction.
Audio capture: mic + system, tagged
Meeting capture records two streams and tags transcript segments by source:
- mic — what the user said locally.
- system — what came out of the speakers (other attendees on Zoom/Meet/Teams calls).
Each transcript segment carries a source: "mic" | "system" tag, which we use to attribute action items to the right attendee. This is why per-attendee action items only work reliably with mic + system capture — mic-only recordings make remote attendees silent. Document this caveat whenever you surface action items.
The iOS/Android companion is intentionally different: mobile background meeting capture is microphone-only because the operating systems do not expose another phone app's Zoom/Meet/Teams audio. It is appropriate for in-person rooms and for capturing audio played from a separate device. Mobile recordings still receive Clips transcription and summaries, but do not promise desktop-quality remote speaker attribution or per-attendee action items.
Bidirectional recording ↔ meeting link
A meeting can have an associated recording, and a recording can be linked back to a meeting:
meetings.recordingId→recordings.idrecordings.meeting_id→meetings.id
Both fields are set by start-meeting-recording. Agents that operate on a recording with a non-null meeting_id should consider both surfaces (a "Clip" answer and a "Meeting" answer can both be valid).
Calendar reminders
Calendar events fire a desktop notification 1 minute before the meeting start and keep it visible until 5 minutes after start unless dismissed (consumer: the desktop tray in src-tauri/). The tray polls list-meetings, which reads Google Calendar live and excludes events the current user has declined, so upcoming reminders do not depend on a manual sync or pre-created meetings rows. The normal Meetings list remains calendar-backed and is not filtered by the reminder-only exclusion. Desktop Zoom joins use Zoom's native zoommtg:// link so the Zoom app opens directly without an intermediate browser tab; unsupported Zoom link shapes and other providers retain their HTTPS join URL. Agents do not need to schedule reminders manually.
Adhoc call detection (desktop macOS)
When meetings are enabled, the desktop polls every 2s for native Zoom (us.zoom.xos / us.zoom.ZoomClips) and Teams (com.microsoft.teams / com.microsoft.teams2), plus browser calls from Chrome, Arc, Safari, and Firefox. Native calls are associated with the conferencing app's process microphone state; browser calls require the active window to belong to a supported browser, its focused page to have an exact HTTPS host for Google Meet, Teams, Zoom, or Webex, and that browser process to be using the microphone. A sustained 3s microphone signal confirms the call. Browser call evidence stays associated with its platform while the user switches to another app, and is cleared after confirmed microphone release or when the signal becomes unreadable for its grace period. A browser microphone by itself, a meeting URL in a background tab, or a lookalike host does not confirm a meeting. CoreAudio reports microphone use per browser process, not per tab, so browser candidates always show a confirmation popup even in Auto mode; its subtitle explains that the active meeting tab is unknown. Native candidates retain Auto-mode start behavior.
After confirmation, Clips matches a nearby calendar meeting or creates an adhoc meeting via create-meeting (source: "adhoc"). Ask mode shows the meeting popup. Auto mode starts native candidates, but browser candidates wait for the user to choose Start notes because microphone activity cannot identify which browser tab is in the call. Detection skips when a meeting is already being transcribed, when Manual mode has the meeting widget disabled, and shortly after a calendar reminder for the same platform. Native detection may fall back to foreground dwell when macOS cannot read the process microphone state; browser detection requires a positive process-microphone signal. Browser URL matching uses macOS Accessibility data, so do not treat an unreadable page as a meeting.
Recording stop has several signals: conferencing-app microphone release is confirmed for 15s, scheduled end is combined with quiet system audio, both audio streams can trigger the longer silence fallback, and sleep is treated as an end signal. Browser adhoc detection carries the exact browser bundle through the meeting prompt so stop monitoring follows the app that confirmed the call; calendar starts infer the app from the join URL or platform. Native auto-stop events retry with backoff until the frontend acknowledges by stopping the detector. The frontend stops through the idempotent stop-meeting-recording action and uses its returned persisted actualEnd as confirmation; it does not read back get-meeting, which hides trashed meetings. Stop and transcript-save requests have 10s deadlines. The final transcript flush happens only after the server confirms the stop; if confirmation or flushing fails, Clips retains the session and retries instead of reporting completion. When quitting during a meeting, Clips waits 15s for teardown, then offers Keep Clips open to continue retries or Quit anyway, which may lose the latest unflushed transcript. A second explicit quit request remains available if the WebView cannot show the recovery dialog. The server stale-meeting sweeper remains a recovery path, not the normal end signal.
Desktop notes also check for web End meeting requests every five seconds while active, and on startup or focus/visibility recovery. start-meeting-recording returns the meeting's captureStopRevision and initial actualEnd; monitoring waits for that startup snapshot. Each stop atomically advances the revision, and the scoped get-meeting-capture-state read returns only that revision and end time, including for trashed meetings. It does not load transcripts, recordings, participants, or action items. A native session stops on a newer revision or a newly changed end timestamp, covering server recovery closures while keeping a meeting's persistent first actualEnd from immediately stopping restarted notes. An untyped route 404 or explicit unknown-action error selects the legacy get-meeting end check on its 30-second cadence, preserving its reopened-note actualEnd limitation until the server supports capture-state. Other failures retry the five-second path without downgrading. Fallback is scoped to the affected session; the next session probes capture-state again. Only one polling path is active. Failed, unavailable, or timed-out checks are logged and retried without overlapping requests; an unavailable response does not establish that the meeting ended.
Actions
| Action | What it does |
|---|---|
list-meetings |
Upcoming + past, scoped via accessFilter; reads connected Google Calendar live. hasContent filters to meetings worth reopening; offset + hasMore page the history. Agent calls get at most 25 meetings per call, each with summaryPreview, hasNotes, actionItemCount, the first 10 participants and participantCount in place of its whole summary, notes, bullets, action items and attendee list; get-meeting has those. Live calendar events merge into the first 1,000 saved meetings; historyCapped: true means older ones remain, reachable with includeLiveCalendar=false and offset, or search-meetings |
search-meetings |
Find a meeting by title, summary, notes, attendee, or linked transcript text, with a match snippet. Use this — not list-meetings — when the user describes what was said rather than when it happened. Agent calls get at most 25 matches, each with summaryPreview, hasNotes, actionItemCount, the first 10 participants and participantCount in place of its whole summary, notes, action items and attendee list |
get-meeting |
One meeting + participants + notes + transcript. Agent calls get the transcript in chunks: pass transcriptOffset from nextFullTextOffset until it is null. The rest comes whole, each detail once: action items only in actionItems, bullets only parsed. Its text carries Me: / Them: labels; segments covers only the start |
create-meeting |
Create a meeting row (source: calendar / adhoc / manual); desktop adhoc Zoom/Teams/Meet/Webex detection passes source: "adhoc" |
update-meeting |
Inline title/notes edits; owner/admin changes to visibility and shareTranscript |
delete-meeting |
Soft-delete a meeting from the visible list; linked recordings and calendar events stay intact |
start-meeting-recording |
Begin native macOS transcript stream + create the linked recording |
stop-meeting-recording |
End the active capture |
finalize-meeting |
Delegate Gemini Flash-Lite cleanup + summary + bullets + action items |
remove-earlier-meeting-audio |
Take audio recovered from before the user started recording out of the transcript, rebuild the notes and the linked Clip's description and generated title, and delete its chapters. get-meeting and view-screen report it as earlierAudioMinutes, which is null when the transcript can't be parsed |
cleanup-transcript |
Shared cleanup pipeline (used by Clips, Meetings, Dictate) |
connect-calendar |
Returns OAuth URL for Google Calendar |
list-calendar-accounts |
What's connected |
sync-calendars |
Compatibility refresh for calendar_events; not needed for the visible list |
disconnect-calendar |
Revoke + clear secret refs |
All actions go through accessFilter / assertAccess. AI work delegates via sendToAgentChat per the delegate-to-agent skill — never inline LLM calls.
Calendar provider-API boundary
These calendar-sourced actions are shortcuts, not a capability ceiling — but do
not add raw provider-api-request access for Google Calendar until the provider
API runtime can resolve Clips calendar_accounts through sharing/access checks
and read their encrypted app_secrets token refs. Clips calendar grants are not
stored in core oauth_tokens, so bypassing that model would break the account
sharing/status boundary.
Sharing meeting notes and transcripts
Meeting share links always include the generated notes: the summary, key
points, and action items. The full transcript appears on the share link and the
agent link only when the meeting's shareTranscript is true. The owner sets
it with Transcript on the share link under Advanced in the Share panel, or
an admin passes shareTranscript to update-meeting.
New meetings start with shareTranscript: true. Meetings created earlier keep
whatever they stored, and any value other than true means off, so never
backfill or default older meetings on. People invited to a meeting see its full
transcript in Clips either way; the switch only governs the link. Sharing a
meeting still must not expose the linked recording's media or comments.
Cleanup credential order
The cleanup-transcript action resolves credentials in this order — always lead with Builder.io Connect when explaining options to the user:
- Builder.io Connect (primary) — managed Gemini 3.1 Flash-Lite. Easiest path; no key required.
- BYOK Gemini (secondary) — user's own
GEMINI_API_KEY(direct to Google). Mention only as a fallback.cleanup-transcriptdoes not call Groq or OpenAI — those are transcription providers (transcribe-voice), not cleanup providers.
Navigation state
The app exposes view, meetingId, and dictationId so the agent always knows what's on screen:
{ "view": "meetings" }
{ "view": "meeting", "meetingId": "mtg_abc" }
{ "view": "dictate", "dictationId": "dct_xyz" }
view-screen output
view-screen auto-includes meeting/dictate context — agents can trust this is present without re-querying. Shape (when on a meeting):
{
"navigation": { "view": "meeting", "meetingId": "mtg_abc" },
"meeting": {
"id": "mtg_abc",
"title": "Weekly Sync",
"scheduledStart": "...",
"scheduledEnd": "...",
"transcriptStatus": "ready",
"shareTranscript": true,
"participants": [{ "email": "alice@ex.com", "name": "Alice" }, ...],
"actionItems": [{ "assigneeEmail": "alice@ex.com", "text": "..." }, ...],
"hasRecording": true,
"recordingId": "rec_xyz"
}
}
When on view: "dictate", the block instead contains a dictation object with id, fullText snippet, cleanedText snippet, durationMs, source. When on view: "meetings" (the list), view-screen returns the upcoming-meetings summary plus calendarAccounts health (status, lastSyncedAt, lastSyncError) instead of a single meeting.
Common tasks
| User request | What to do |
|---|---|
| "Show me my meetings today" | pnpm action navigate --view=meetings |
| "Open my 3pm call with Alice" | Look up via list-meetings, then pnpm action navigate --view=meeting --meetingId=<id> |
| "Summarize the standup I just finished" | pnpm action finalize-meeting --id=<id> (delegates to agent for Gemini cleanup) |
| "Create a meeting note for the call I just finished" | Prefer the current calendar event. If it was not on the calendar, send the user to /record instead of creating a fake meeting from the UI. |
| "Connect my Google Calendar" | pnpm action connect-calendar --provider=google then open returned authUrl |
| "Show my action items from last week" | list-meetings --view=past --hasContent, then collect actionItemsJson and filter by assigneeEmail |
How the agent uses Meetings
These flows are common enough to memorize:
- "Summarize my last meeting with Alice" —
search-meetings --query=alice, pick the most recent,get-meeting, thenfinalize-meetingifsummaryMdis empty. - "Find the call where we discussed the renewal" —
search-meetings --query="renewal". It reads transcripts, so it finds calls the user never titled usefully;list-meetingscannot answer this. - "Show me action items I owe Bob" —
list-meetings(recent), aggregateactionItemsJson, filterassigneeEmailmatching Bob's email. Mention the mic+system caveat if the user expects coverage of remote attendees. - "Create a meeting note for the call I just finished" — prefer an existing calendar-synced meeting. If the call was not on the calendar, send the user to
/record; do not invent a fake calendar meeting in the visible Meetings list. - "What did Alice commit to in last Tuesday's standup?" —
get-meeting, scanactionItemsJsonfiltered by assignee, fall back to grepping the transcript segments taggedsource: "system"(since Alice is remote).
UI conventions (don't break)
- Upcoming is one compact card ("Coming up"), never a tile grid: a date column per day, one line per event, and Join / Open notes only on the live or imminent row. It must not push history below the fold.
- History is dense one-line rows, grouped by day with a date header (Today / Yesterday / Weekday Date): attendee avatars, title, attendee names, right-aligned time. No summary preview and no per-row status pills — transcript/notes state belongs on the detail page, not repeated down a list.
- History is paged, never capped. The list reads
list-meetingswithhasContent: true(notrecordedOnly) so desktop live notes without a linked recording still appear, and pages withoffset+hasMorebehind a "Load older" button. - The search box is server-side, calling
search-meetings. Never filter the loaded page client-side: the meeting a user is hunting for is usually one they have not scrolled to. - Calendar-sourced list: no "New meeting" CTA and no manual sync requirement in the Meetings list. Users connect/reconnect/disconnect the calendar from the calendar settings menu; events are fetched live from Google Calendar.
- Two-pane detail: transcript (left) + AI notes (right) with a "Generate notes" button in the header.
- Live indicator is a red animated dot — never a sparkle or a robot icon.
- Calendar empty state uses one focused Google Calendar CTA card.
- shadcn components only. Tabler icons (
IconCalendar,IconMicrophone2,IconWand,IconNotes). No emojis as icons. No sparkle/robot.