Realtime Sync

The bee stream command provides real-time event streaming from your Bee device, allowing you to receive live updates as conversations happen and data changes.

bee stream is real-time and does not guarantee delivery (at-most-once semantics). The stream requires an active internet connection, and events that occur while disconnected will not be received. If you need reliability/completeness, prefer a full bee sync snapshot.

Basic Usage


# Human-readable with colors (default)
bee stream
 
# Human-readable, token-optimized for inference (no colors)
bee stream --agent
 
# Structured JSON output
bee stream --json

This starts a persistent connection that outputs events as they occur.

Event Types

The stream emits the following event types:

Connection Events

Event	Description
`connected`	Successfully connected to the stream

Conversation Events

Event	Description
`new-utterance`	A new utterance was captured
`new-conversation`	A new conversation started
`update-conversation`	An existing conversation was updated

Todo Events

Event	Description
`todo-created`	A new todo was created
`todo-updated`	An existing todo was updated
`todo-deleted`	A todo was deleted

Journal Events

Event	Description
`journal-created`	A new journal entry was created
`journal-updated`	An existing journal entry was updated
`journal-deleted`	A journal entry was deleted

Output Modes

Default mode (`bee stream`)

Human-readable stream output with colors for terminal usage.

Agent mode (`bee stream --agent`)

Human-readable output optimized for inference/token efficiency, with no color formatting.

JSON mode (`bee stream --json`)

JSON objects, one per line, for programmatic parsing:


{"event":"connected","timestamp":"2024-01-15T10:30:00Z"}
{"event":"new-utterance","data":{"text":"Hello","speaker":"user"},"timestamp":"2024-01-15T10:30:05Z"}
{"event":"new-conversation","data":{"id":"123","title":"Morning chat"},"timestamp":"2024-01-15T10:30:10Z"}

Use Cases

Real-Time Dashboard

Pipe stream output to build live dashboards:


bee stream | while read event; do
  echo "$event" >> ~/bee-events.log
  # Process event...
done

Integration with Other Tools

Send events to external services:


bee stream --json | while read event; do
  curl -X POST https://your-webhook.com/bee \
    -H "Content-Type: application/json" \
    -d "$event"
done

Live Notifications

Create desktop notifications for new conversations:


bee stream --json | jq -r 'select(.event == "new-conversation") | .data.title' | while read title; do
  osascript -e "display notification \"$title\" with title \"New Conversation\""
done

Logging

Create a persistent log of all Bee activity:


bee stream >> ~/bee-activity-$(date +%Y-%m-%d).log

Processing with jq

Use jq to filter and transform events:


# Only show new utterances
bee stream --json | jq 'select(.event == "new-utterance")'
 
# Extract just the text from utterances
bee stream --json | jq -r 'select(.event == "new-utterance") | .data.text'
 
# Count events by type
bee stream --json | jq -r '.event' | sort | uniq -c

Running in the Background

Run the stream as a background process:


# Start in background
nohup bee stream >> ~/bee-events.log 2>&1 &
 
# Or use screen/tmux
screen -dmS bee-stream bee stream

The stream automatically reconnects if the connection is lost. There’s no need to manually handle reconnection.

Example: Building a Live Feed

Here’s a complete example that creates a live feed of your conversations:


#!/bin/bash
 
echo "Starting Bee live feed..."
 
bee stream --json | while read -r line; do
  event=$(echo "$line" | jq -r '.event')
 
  case $event in
    "connected")
      echo "[Connected to Bee stream]"
      ;;
    "new-utterance")
      text=$(echo "$line" | jq -r '.data.text')
      speaker=$(echo "$line" | jq -r '.data.speaker')
      echo "[$speaker]: $text"
      ;;
    "new-conversation")
      title=$(echo "$line" | jq -r '.data.title')
      echo "--- New conversation: $title ---"
      ;;
    "todo-created")
      todo=$(echo "$line" | jq -r '.data.title')
      echo "[New Todo]: $todo"
      ;;
  esac
done