The Capture Queue

Glassy Companion is designed so that a missing network connection never loses a capture. If your Glassy server is unreachable — whether you’re on a plane, your server is restarting, or your Wi-Fi is acting up — the extension catches the failure and queues the capture locally.

How the queue works

The queue lifecycle:

1. Capture triggered — you press a shortcut or click the extension
2. Server unreachable — the POST request fails (network error, timeout, or 5xx)
3. Queue storage — the full capture payload (title, URL, Markdown body, tags, collection, metadata) is stored in chrome.storage.local
4. Periodic retry — every 60 seconds, the extension checks if the server is reachable
5. Flush — when the server responds, all queued items are sent (batched in parallel since v2.3.2)
6. Confirmation — each successful flush shows a toast notification

What gets queued

Capture type	Queues?	Notes
Full page	Yes	Content is extracted and stored as text
Selection	Yes	Highlighted text with source URL
Bookmark	Yes	URL and metadata
Quick Note	Yes	Note body
Screenshot (text portion)	Yes	Capture metadata queued
Screenshot (image upload)	Retried separately	Image upload uses a 3-attempt backoff, separate from the capture text

How to tell you’re offline

When a capture fails and enters the queue:

• A badge number appears on the Glassy extension icon
• The popup shows an “Items queued” indicator with the count
• A toast notification says “Server unreachable — saved to queue”

When does the queue flush?

The extension attempts to flush:

• Automatically, every 60 seconds in the background
• When you open the popup — a flush is triggered immediately
• When connectivity is detected — the extension listens for network change events

All queued items are attempted in parallel (since v2.3.2). Even a backlog of 50 items clears in one round-trip per batch.

Inspecting the queue

Manually flushing the queue

If you know your server is back online and the automatic retry hasn’t triggered yet:

1. Open the Companion popup
2. Click Flush queue now
3. The extension sends all queued items immediately
4. If successful, the badge clears and a confirmation toast appears

Clearing the queue

If you want to discard queued items (e.g., they’re no longer relevant):

1. Open the popup → Settings → Debug → Offline Queue
2. Click Clear queue
3. Confirm — items are permanently discarded

Verifying sync after reconnection

After coming back online:

1. Wait up to 60 seconds for the automatic flush
2. Open Glassy and check your library — queued captures should appear
3. Captures arrive with their original capture timestamp (not the sync time)
4. If captures are missing, open the popup and click Flush queue now
5. When the queue is empty, the badge disappears — a clear badge means everything synced

Troubleshooting a stuck queue

Queue shows items but the badge never clears:

1. Open the popup → check Settings → Server URL. Make sure it points to your actual Glassy server.
2. Check that you can reach the server — open the URL in a browser tab.
3. Look in Debug → Offline Queue for the error detail. Common causes: expired session token, server returning 5xx, or wrong server URL.

Queue cleared but captures missing from library:

This is rare. If the badge cleared (server returned 2xx), the capture was accepted. Search the library by URL. If still missing, the server may have had a database error — check server logs:

docker logs glassy-dash-prod | grep "POST /api/captures" | tail -20

What’s next?

Learn about multi-account capture — routing captures to different Glassy accounts from the same extension.