Documentation

Everything you need to get started with CC Break Monitor.

Overview

CC Break Monitor automatically tracks your active, break, and offline time on Command Center for AWS Support agents. It runs as a browser extension for Firefox and Chrome — no manual input required.

The extension monitors Command Center API calls in the background, categorises each status change, and shows a live panel with your daily totals, weekly goal, and progress toward your active time target. A day-level Deep Dive, a 4-week history, optional self-hosted cross-device sync, and CSV/JSON exports round out the picture.

Features at a Glance

See the full features page for detailed descriptions. A summary of each capability follows below.

Feature Reference

⏱️ Auto-Detection

The extension monitors Command Center API calls to detect status changes automatically — no manual input, no buttons to press. It intercepts PUT calls to the general status endpoint (watcher-iad.dre.kumo…/v1/agent/status) and the case-specific endpoint (global.api.gaderian…/agent/status), then reads the current status from the page's DOM badge and records the transition. A DOM-polling fallback (10-second interval) catches any change the request interceptor misses.

📊 Time Tracking

Every status change is logged with a timestamp and categorised into three buckets — Active (counts toward target), Break, and Offline. Time is tracked at second-level precision and displayed at minute precision (7h 46m). The status lists cover the full set of Command Center CCP aux states; unrecognised statuses default to Active, so new CC statuses work without an extension update. Past-day totals are reconciled from the raw transition stream and segments that span midnight are split across days, so time is never lost or double-counted.

🎯 Daily Target

Set a configurable daily active-time goal in Settings (default 7h 46m, region-adjustable). The panel shows a live countdown of remaining time, a real-time progress indicator, and a surplus summary once the target is met.

📅 Weekly Goal & 4-Week History

A 📅 Week section in the panel and popup shows this week's total active hours, daily average, and remaining hours toward a configurable weekly target (default 38h 50m). The popup also displays the current week plus the previous three weeks — total hours and daily average each — for spotting trends. The work week is fully configurable: choose the week start day and work days per week (1–7, default 5), with a live preview of the computed range (e.g. Mon–Fri, Sun–Thu). Weekly bounds recalculate immediately when these settings change.

🔬 Deep Dive Day View

Click any day cell to open a day-level Deep Dive: an Active-vs-Break balance chart plus a scrollable Work/Break timeline of that day's status segments (start–end, category, duration). Each day cell also shows a slim in-cell Active/Break/Offline proportion bar, and the current day is highlighted.

🍩 Donut / Bars Toggle

The day breakdown renders as either a conic-gradient donut or a vertical bar chart (Active / Break / Offline). The choice persists for the session.

🏖️ Leave Marker (Working ⇄ Absent)

A two-state marker lets you flag a day as Working or Absent/Sick, with Save/Discard for unsaved changes. A day marked Absent is credited as a full working day at your Daily Target — it counts toward the weekly average and weekly target, so paid leave no longer drags the average down. The "Worked" column still shows real tracked active time. Expected days off can be hidden from the grid (default hidden).

↺ Reset View

The ↺ button zeroes the displayed timers for a clean visual starting point mid-shift. This is view-only — it does not modify stored data, clears automatically on page reload, and your accumulated totals and exports remain intact.

◐ Theme Toggle

Click ◐ to cycle Dark, Light, and System (follows your OS via prefers-color-scheme). Themes use CSS custom properties and apply to the panel, toolbar popup, and options page. The panel and popup use a modern dashboard theme with summary cards ("Today's Productivity", "Week's Active Time", "Weekly Target" with a progress bar).

📌 Docked & Floating Panel

The panel runs docked into the Command Center widget area, or floating as a movable overlay. In floating mode, drag the header handle to reposition it; the position persists across page reloads. The docked view scrolls horizontally in narrow layouts so nothing clips.

📥 Export Reports

Two one-click exports from the panel header and toolbar popup:

• Today — CSV daily report cc_monitor_today_YYYY-MM-DD.csv with columns Day, From, To, FromCategory, ToCategory, Duration, Timestamp, ShownInUI. All transitions are included; ShownInUI marks the ones visible in the panel.
• Backup — JSON full backup cc_monitor_backup_YYYY-MM-DD.json containing exportedAt, dailyTotals, changeLog, and allTransitions.

Files land in your browser's Downloads folder; an optional subfolder is configurable in Settings.

🔄 Cross-Device Sync

Sync is optional and self-hosted. Deploy a CloudFormation stack in your own AWS account to create a lightweight backend — HTTP API Gateway, a Lambda handler, two DynamoDB tables, and a least-privilege IAM role. On startup the extension pulls remote data and merges it with local state; on every status change it pushes an update; and a periodic push every 5 minutes catches anything missed. Conflict resolution takes the higher value for daily totals, deduplicates change logs by timestamp, and uses the latest timestamp for current status. Cost is effectively $0/month within the Free Tier, and data auto-expires after 90 days via DynamoDB TTL. See the landing page for the one-click deploy link.

⬆️ Force Push / Force Pull

Sync settings include manual controls for edge cases:

• Force Push — pushes all local data (today + full history) to DynamoDB, throttled to respect rate limits. Useful right after a fresh backend deploy when the table is empty but your browser has weeks of data.
• Force Pull — fetches up to 90 days of history from DynamoDB and merges it into local storage, restoring the weekly summary after a reinstall or on a new device.

🔐 API-Key Security

The sync backend authenticates every request (except /config) with an X-Api-Key header. Keys are SHA-256 hashed at rest and scoped per alias, so you can only read and write your own data. CORS is restricted to extension origins and the internal landing-page domain, the Chrome bridge uses a per-page-load nonce on its postMessage channel, both manifests declare an explicit Content Security Policy, and the API Gateway applies stage-level rate limiting. Generate and manage keys with the copyable command in the options page.

🔒 Privacy First

All data is stored locally in browser.storage.local by default. No analytics, no telemetry, no third-party services. The Firefox manifest declares data_collection_permissions: required: ["none"], permissions are scoped to the specific CC and API domains, and cross-device sync is opt-in in your own AWS account. All source is readable and auditable. Distribution links resolve only from the internal AWS network.

🔁 Auto-Updates

Firefox: signed via Mozilla AMO (unlisted) with an update_url pointing to updates.json on CloudFront; Firefox checks roughly every 24 hours and installs silently (force-check via about:addons → gear → "Check for Updates"). Chrome Web Store: auto-updates every few hours. Chrome Developer Mode: download the latest .zip and reload at chrome://extensions/.

🗂️ Multi-Tab Support

A single background script (Firefox) or service worker (Chrome) runs once regardless of how many Command Center tabs or windows are open. Each status change is recorded exactly once, all tabs receive the same data via message broadcasting, and no leader election or tab coordination is needed — the background process is the single source of truth.

Quick Start — Firefox

1. Download the latest signed .xpi: cc_break_monitor-latest.xpi
2. Firefox will prompt you to install — click Add.
3. Open Command Center. The panel appears automatically.

Updates are automatic. Firefox checks roughly every 24 hours. Force-check via about:addons → gear icon → "Check for Updates".

Quick Start — Chrome

Option A — Chrome Web Store (when approved)

Install from the Web Store listing. Auto-updates are handled by Chrome.

Option B — Developer Mode (available now)

1. Download the latest .zip: cc_break_monitor-chrome-latest.zip
2. Unzip the file.
3. Open chrome://extensions/ → enable Developer mode (top-right toggle).
4. Click Load unpacked → select the unzipped folder.
5. Open Command Center.

Project Structure

Settings Reference

The options page exposes:

• Daily Target — active-time goal (default 7h 46m, region-adjustable).
• Weekly Target — weekly active-hours goal (default 38h 50m).
• Week starts on and Work days per week — auto-save on change (debounced) with a live day-range preview.
• Timezone — drives day rollover and date-aware sync.
• Theme — Dark / Light / System.
• Hide expected days off from the grid (default on).
• Download subfolder for CSV/JSON exports.
• Sync — API URL, alias, and API key, plus Force Push / Force Pull buttons and a copyable key-generation command.

Building & Publishing

What the script does

1. Checks that CHANGELOG.md has an entry for the new version
2. Bumps the version in both manifests
3. Builds and signs the Firefox .xpi via Mozilla AMO (unlisted)
4. Builds the Chrome .zip and publishes to the Web Store (if credentials are set)
5. Updates the landing page with the new version
6. Uploads artifacts to S3, including a permanent copy under releases/<version>/
7. Invalidates the CloudFront cache
8. Commits the bump, tags it vX.Y.Z, and pushes the commit + tag

Prerequisites

• npm install -g web-ext
• AWS CLI configured (for S3 upload + CloudFront invalidation)
• Required: Mozilla AMO credentials (AMO_JWT_ISSUER, AMO_JWT_SECRET)
• Required: a CHANGELOG.md entry for the new version (override with --skip-changelog-check)
• Optional: Chrome Web Store credentials for auto-publish

Rolling Back

Every build is archived under releases/<version>/ in S3, so you can promote a previous release back into the -latest slot without rebuilding:

See docs/ROLLBACK.md for distribution vs code-level rollback procedures.

Version Scheme

Versions follow MAJOR.MINOR.PATCH with rollover:

• Patch increments normally: 1.4.0 → 1.4.1 → … → 1.4.9
• Patch rolls over at 9: 1.4.9 → 1.5.0
• Minor rolls over at 9: 1.9.9 → 2.0.0