Meeting Assistant

intent

automate meeting capture on macOS by detecting active calls (Zoom, Google Meet, Feishu, WeChat, etc.), prompting the user to start recording, capturing system audio and microphone input via ScreenCaptureKit, transcribing locally with whisper-cli, and queueing final summaries to an OpenClaw agent. use this when you need hands-off meeting documentation without virtual audio devices or cloud transcription services.

inputs

macOS environment:

• macOS 12.0 or later (ScreenCaptureKit requirement)
• Homebrew installed
• Python 3.8+

external connections:

• Google Calendar (optional): OAuth 2.0 desktop client credentials stored locally; refresh tokens in system Keychain via gog CLI
  • setup: run gog auth credentials ~/Downloads/client_secret_xxx.json && gog auth add your.email@example.com --services calendar after Google Cloud Console OAuth setup
  • env var: none (Keychain-backed; config points to gog_account string in ~/.config/meeting-assistant/config.json)
  • scope: https://www.googleapis.com/auth/calendar.readonly

system permissions required:

• Microphone (for AudioDaemon.app)
• Screen & System Audio Recording (for ScreenCaptureKit)
• Accessibility (for window_scanner binary to detect meeting windows)

local files/config:

• ~/.config/meeting-assistant/config.json (created by setup.sh)
• ~/.config/meeting-assistant/audio_daemon.sock (Unix socket for AudioDaemon)
• meeting recordings directory (default: ./meeting-recordings/)
• whisper model file (default: ~/Models/whisper/ggml-medium.bin)

optional integrations:

• OpenClaw agent queue (~/.config/meeting-assistant/agent-queue.json) for summary generation
• Telegram, Zulip, or Notion webhook URLs (optional output in config)

procedure

1. install and configure

   • input: clean macOS machine with Homebrew
   • run git clone https://github.com/Nowhitestar/meeting-assistant.git && cd meeting-assistant && bash scripts/setup.sh
   • output: AudioDaemon.app signed and installed, LaunchAgent services registered, config.json created, all TCC permissions prompted and recorded

2. scheduler daemon starts

   • input: ~/.config/meeting-assistant/config.json with calendar enabled
   • background process scheduler_daemon.py queries Google Calendar (or local calendar) every 60 seconds
   • output: schedule.json written with upcoming meetings in next 8 hours

3. meeting detector monitors windows

   • input: window_scanner binary (Accessibility-gated) polls active windows every 2 seconds
   • detects: Zoom, Tencent Meeting, Google Meet, Feishu/Lark, WeChat, and generic browser-based meetings
   • output: meeting detected event passed to meeting_daemon.py if window title matches known meeting apps

4. user is prompted to record

   • input: meeting detection trigger
   • meeting_daemon.py ask_record calls notify.py which displays native macOS notification with "Start Recording?" prompt
   • user clicks yes or no
   • output: recording decision (boolean) returned to meeting_daemon

5. recording starts (if approved)

   • input: user approval + meeting title + meeting ID
   • record_audio.py start sends command via Unix socket to AudioDaemon.app
   • AudioDaemon connects to ScreenCaptureKit for system audio, AVFoundation for microphone
   • half-duplex mixing: system audio prioritized; microphone fades in when system audio drops below silence threshold
   • output: stereo WAV file written to output_dir/TIMESTAMP_meeting-title.wav

6. recording ends (manual or auto-silence)

   • input: user stops manually (record_audio.py stop) or 5-minute silence detected
   • AudioDaemon stops stream, flushes WAV to disk
   • output: finalized WAV file with system audio + microphone tracks

7. transcription runs locally

   • input: WAV file path
   • transcribe.py spawns whisper-cli (local binary, no cloud upload)
   • whisper-cli loads model from local_model_path and outputs text to TIMESTAMP_meeting-title.txt
   • output: transcript.txt in same directory as WAV

8. summary request queued for OpenClaw agent

   • input: transcript.txt + summary_template.md
   • transcribe.py writes entry to ~/.config/meeting-assistant/agent-queue.json with transcript path and template
   • output: JSON queue entry with summary_request action

9. OpenClaw heartbeat agent processes summary

   • input: reads from agent-queue.json (external agent process)
   • agent reads transcript and template, calls LLM to generate final notes
   • output: TIMESTAMP_meeting-title-summary.md written to meeting-recordings directory

10. user notified of completion

    • input: summary.md written to disk
    • agent_notify.py or send_summary.py sends macOS notification and optionally posts to Telegram/Zulip/Notion
    • output: user sees "Meeting summary ready" notification with link to notes file

decision points

if Google Calendar is enabled:

• scheduler_daemon.py queries Calendar API every 60 seconds
• if upcoming meeting exists within 8 hours and is not already marked recorded, prepare for detection phase
• else: skip scheduler, only rely on window detection

if meeting window is detected:

• check if this meeting is already being recorded (check PID in agent-queue or recording status)
• if yes: skip prompt
• if no: proceed to user prompt

if user declines recording prompt:

• meeting_daemon.py logs decision and stops
• no WAV is created; no transcript queued

if system audio permission is missing:

• AudioDaemon reports sysReady=false in status
• record_audio.py refuses to start recording; notifies user to enable Screen & System Audio Recording in System Settings
• recording is blocked until permission is granted

if microphone permission is missing:

• AudioDaemon reports micReady=false in status
• recording will proceed but microphone track will be silent; warning shown to user

if Accessibility permission is not granted:

• window_scanner fails to read window titles
• meeting detection falls back to calendar-only mode (if Calendar enabled) or manual trigger only

if WAV file is created but is silent:

• likely cause: TCC permission not yet active or daemon not ready
• transcribe.py warns user and still queues summary request (will generate empty notes)
• user can manually check echo '{"action":"status"}' | nc -w 2 -U ~/.config/meeting-assistant/audio_daemon.sock to verify AudioDaemon readiness

if whisper-cli transcription fails (timeout, model missing, out of memory):

• transcribe.py catches exception, logs error, and still queues summary_request with empty transcript
• OpenClaw agent receives error status in queue entry

if OpenClaw agent is not running or agent-queue is stale:

• summary_request sits in queue indefinitely
• user can manually call python3 scripts/send_summary.py to finalize summary or check queue with cat ~/.config/meeting-assistant/agent-queue.json

if Google Calendar refresh token expires:

• scheduler_daemon.py fails to query Calendar; logs error
• meeting detection falls back to window detection only
• user must re-authorize: gog auth add your.email@example.com --services calendar

if network is offline (Keychain sync, cloudflared tunnel for webhooks):

• Calendar fetch fails gracefully; window detection continues
• local transcription and agent queue writing are unaffected (both offline-capable)

output contract

success state:

• meeting recording exists at {output_dir}/{TIMESTAMP}_{meeting_title}.wav (stereo, 16-bit PCM, sample rate per config)
• transcript exists at {output_dir}/{TIMESTAMP}_{meeting_title}.txt (plain text, one line per utterance or paragraph per speaker, depending on whisper output)
• summary request entry in ~/.config/meeting-assistant/agent-queue.json with schema:

  {
    "id": "uuid",
    "action": "summary_request",
    "timestamp": "2024-01-15T10:30:00Z",
    "transcript_path": "/path/to/transcript.txt",
    "template_path": "/path/to/summary_template.md",
    "meeting_title": "Project Sync",
    "status": "pending"
  }
  

• final summary at {output_dir}/{TIMESTAMP}_{meeting_title}-summary.md (Markdown, generated by OpenClaw agent)
• macOS notification sent to user with meeting title and link to summary file
• (optional) Telegram/Zulip/Notion message posted if webhook URL configured

file locations:

• recordings: {config.audio.output_dir}/ (default: ./meeting-recordings/)
• config: ~/.config/meeting-assistant/config.json
• agent queue: ~/.config/meeting-assistant/agent-queue.json
• AudioDaemon socket: ~/.config/meeting-assistant/audio_daemon.sock
• logs: not explicitly defined; check stderr/system log via log stream --predicate 'process == "AudioDaemon"'

data format:

• WAV: stereo, 16-bit signed PCM, sample rate 44.1 kHz or 48 kHz
• transcript: UTF-8 text, language per config (default Chinese)
• summary: UTF-8 Markdown
• agent queue: JSON Lines (one JSON object per line) or single JSON array

outcome signal

• user receives native macOS notification ("Meeting Recorded and Transcribed") with title and file path
• summary.md file is readable and contains coherent meeting notes (not just raw transcript)
• record_audio.py status or AudioDaemon socket query shows recording=false and lastMeeting={title} after recording stops
• no error logs in console or system log mentioning AudioDaemon, whisper, or agent queue
• user can manually verify: ls -la ~/.config/meeting-assistant/meeting-recordings/ shows recent .wav, .txt, and -summary.md files with current timestamps

credits: original skill by Nowhitestar (GitHub: nowhitestar/meeting-assistant). enriched for Implexa standards.