| name | rebecca-monitor |
| description | Debug live Zoom meeting-agent failures for Rebecca/Bighead. Use when messages are missed, meeting jobs are stuck, transcripts stop, or live triage needs an event tail. |
| policy_doc_kind | skill |
| classification | canonical |
| canonical_owner | self |
| authority_level | procedural |
| in_verifier_scope | true |
/rebecca-monitor
Real-time diagnostic aggregator for the Rebecca + Bighead meeting pipeline. Pulls data from all subsystems (Flask logs, SQLite, Recall.ai API, ngrok, Bighead) into a single structured view for rapid debugging.
Usage
/rebecca-monitor # Full diagnostic snapshot
/rebecca-monitor --watch # Continuous monitoring (re-run every 10s)
/rebecca-monitor --meeting <id> # Deep-dive on specific meeting
/rebecca-monitor --errors # Errors and warnings only
/rebecca-monitor --transcript <id> # Full transcript for a meeting
/rebecca-monitor --webhooks # Recent ngrok webhook traffic
Flags
| Flag | Effect |
|---|
--watch | Re-run monitor every 10 seconds, diff output between runs |
--meeting <id> | Focus on a single meeting: full state, transcript, bot status, voice events |
--errors | Filter to ERROR/WARNING log lines + failed webhooks + error states |
--transcript <id> | Dump full transcript segments for a meeting with speaker/timing |
--webhooks | Show last 20 ngrok-captured requests with status codes and bodies |
--recall | Show all Recall.ai bot statuses via API |
--voice | Show voice pipeline state: wake word detections, TTS calls, debounce |
--json | Machine-readable JSON output instead of formatted text |
Workflow
1. Run the monitor script
cd ~/chad_bot_attempt/cw-nemo/cw/code/rebecca_2.0
source .venv/bin/activate && python scripts/monitor.py [flags]
The script aggregates from 6 data sources:
| Source | What it provides |
|---|
logs/qa_bot.log | Request logs, meeting events, voice pipeline, errors |
data/state.db | Meeting records, transcript segments, bot mappings |
| Recall.ai API | Live bot status, transcript, recording URLs |
| ngrok API (localhost:4040) | Inbound webhook requests from Recall.ai |
| Bighead API | Health status, transcript analysis availability |
| Process list | Flask/ngrok/tunnel process health |
2. Interpret the output
The monitor outputs sections:
SERVICES — health of each component (Rebecca, Bighead, ngrok, SSH tunnel)
MEETINGS — active and recent meetings with state, bot_id, timestamps
BOT STATUS — Recall.ai bot lifecycle state (joining → waiting room → recording → done)
TRANSCRIPTION — segment count, last segment time, speakers detected, word count
WEBHOOKS — recent inbound requests: path, status code, timestamp, body preview
VOICE — wake word detections, TTS invocations, response latency
ERRORS — aggregated errors from all sources in chronological order
ID MAPPINGS — meeting_id ↔ bot_id ↔ audio_bot_id ↔ livekit_room cross-references
3. Debug common issues
| Symptom | Check | Likely cause |
|---|
| Bot not joining | BOT STATUS shows READY or ERROR | Meeting URL invalid, Recall.ai quota, or meeting hasn't started |
| Bot stuck in waiting room | BOT STATUS shows IN_WAITING_ROOM | Host hasn't admitted bot; check Zoom meeting settings |
| No transcription arriving | WEBHOOKS section empty | ngrok not running, webhook URL wrong, or signature verification failing |
| Webhook 401s | ERRORS section | RECALL_TRANSCRIPTION_SECRET mismatch between .env and Recall.ai config |
| Voice not responding | VOICE section shows no wake words | Wake word not detected, or debounce blocking (1s cooldown) |
| Transcript analysis failing | BIGHEAD section unhealthy | SSH tunnel down, or Bighead container crashed on inference_box |
| Meeting shows "abandoned" | MEETINGS status=abandoned | Bot was in joining/waiting >30 min, auto-cleaned by cleanup_abandoned() |
4. Deep-dive workflow
When a specific problem is found:
- Run
--meeting <id> for full meeting context
- Run
--webhooks to see if Recall.ai is sending data
- Run
--transcript <id> to see what was captured
- Check
--errors for any stack traces
- If Bighead-related:
curl http://localhost:8000/health and check SSH tunnel
- If Recall-related:
--recall to see bot status directly from Recall.ai API
Key file paths
| File | Purpose |
|---|
scripts/monitor.py | The monitoring script |
logs/qa_bot.log | Flask application log |
data/state.db | SQLite database with meetings + transcripts |
.env | Environment configuration (API keys, URLs) |
src/meeting/recall_client.py | Recall.ai API wrapper |
src/meeting/meeting_handler.py | Meeting lifecycle manager |
src/meeting/transcription.py | Transcript processing |
src/voice/voice_pipeline.py | Voice response pipeline |
Environment requirements
- Rebecca Flask running (default port 5050 locally)
- ngrok running and forwarding to Rebecca
- SSH tunnel to inference_box for Bighead (port 8000)
- Python venv activated with project dependencies
