Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Synheart Behavior Chrome Extension extends behavioral input to the desktop browser. It captures how you interact with Chrome — rhythm, attention, movement patterns — not what you read or type, and streams anonymized session events to your local Synheart Sensor Agent. It produces the same event shape as the mobile SDKs (Flutter, Kotlin, Swift), so the browser becomes another input source for the same downstream pipeline. As with the mobile SDKs, the extension is an input layer; higher-level metrics (focus, distraction, HSI fields) are derived downstream — see the Behavior overview. Distribution: Source-available. The repository is open for reading, auditing, and filing issues. Pull requests are not accepted — see the repo’s CONTRIBUTING.md. Security reports follow SECURITY.md.

​
Privacy posture

The extension records interaction timing and patterns only. It does not record URLs, page titles, passwords, or typed content. Tabs use anonymous labels (tab-1, tab-2). Sites are classified into generic categories only.
CapturedNever captured
Mouse movement patterns (not precise positions tied to page content)URLs or page titles
Keystroke timing (categories: letter / digit / symbol — never which key)Typed content, passwords, or search queries
Tab-switch timing with anonymized tab IDsClipboard, form values, or link destinations
Scroll patterns and reversalsMedia URLs
Generic site categories—

​
Site categories

CategoryExamples
search-engineGoogle, Bing, DuckDuckGo
video-platformYouTube, Vimeo, Twitch
code-repositoryGitHub, GitLab, Bitbucket
developer-qaStack Overflow, Stack Exchange
social-mediaFacebook, X, LinkedIn
forumReddit
e-commerceAmazon, eBay
emailGmail, Outlook
documentationGoogle Docs, Notion
local-developmentlocalhost, 127.0.0.1
websiteDefault for other sites

​
Installation

​
From source

git clone https://github.com/synheart-ai/synheart-behavior-chrome.git
cd synheart-behavior-chrome
npm install
npm run build
Load the extension in Chrome:
  1. Open chrome://extensions
  2. Enable Developer mode
  3. Click Load unpacked and select the dist folder
For iterative development, run npm run build -- --watch and use Reload on the extension card after each change.

​
Requirements

  • Chrome (Manifest V3)
  • A running Synheart Sensor Agent reachable on a configured host/port (typically 127.0.0.1)

​
Quick start

  1. Start the sensor agent.
  2. Open the extension popup, go to Sensor, set the port and auth token, choose Save, then Test Connection.
  3. Toggle the main switch to ON to begin capture. Use Stats and HSI in the popup to verify flow.
There is no account in this repo — only your local configuration.
TabPurpose
StatsBuffered events, session id, sensor-agent status.
SensorPort, auth token, test + save.
HSILatest human-state readouts when your agent returns them.

​
Behavioral metrics captured

​
Focus and attention

MetricDescription
Tab switchMoves between tabs (anonymized IDs).
Tab hijackingRapid tab switches within a short window (e.g. 5 seconds).
Window focus / blurBrowser focus at the OS level.
Visibility changeTab hidden / visible transitions.
Cursor parkingWhere the cursor settles (e.g. by quadrant).

​
Micro-motor patterns

MetricDescription
Cursor path tortuosityMovement efficiency (1.0 ≈ straight; higher ≈ more hesitant).
Click dwellHow long the mouse button is held.
Scroll eventsVelocity, direction, ratchet vs linear.
Scroll reversalsDirection flips (re-reading–style signal).

​
Keystroke dynamics (timing only)

MetricDescription
Key hold timeBy category (letter, digit, symbol) — never which key.
Flight timeGap between releasing one key and pressing the next.
Backspace burstRapid backspace bursts (e.g. 3+ in 500ms).
Modifier combosCtrl / Alt / Shift / Meta usage patterns.
MetricDescription
Navigation eventsTransition type (typed, link, reload, generated).
Anchor scanningLink hover duration, internal vs external.
Form submitGET vs POST (method only).

​
Session payload

The extension batches browser events into session payloads and POSTs them to the sensor agent. 
{
  "session": {
    "session_id": "SESS-1705334400000",
    "device_id": "chrome-abc12345",
    "timezone": "America/New_York",
    "start_time": "2024-01-15T10:00:00.000Z",
    "end_time": "2024-01-15T10:05:00.000Z",
    "events": [
      {
        "timestamp": "2024-01-15T10:00:05.000Z",
        "event_type": "app_switch",
        "app_switch": {
          "from_app_id": "tab-1",
          "to_app_id": "tab-2",
          "site_category": "code-repository"
        }
      },
      {
        "timestamp": "2024-01-15T10:00:10.000Z",
        "event_type": "scroll",
        "scroll": {
          "velocity": 150,
          "direction": "down",
          "direction_reversal": false
        }
      },
      {
        "timestamp": "2024-01-15T10:00:15.000Z",
        "event_type": "typing",
        "typing": {
          "key_category": "letter",
          "hold_ms": 85,
          "flight_ms": 120
        }
      }
    ],
    "meta": {
      "source": "synheart-behavior-chrome",
      "version": "0.0.1",
      "event_count": 45
    }
  }
}

​
Event type mapping

Browser conceptevent_type
Tab switchapp_switch
Scrollscroll
Click dwelltap
Cursor pathswipe
Keystroke timingtyping
Focus / blurfocus
Idleidle
Navigationnavigation

​
Sensor agent endpoint

POST http://127.0.0.1:{port}/collect
Authorization: Bearer {token}
Content-Type: application/json
Body: { "session": { ... } } as produced by the extension. Response shape varies with agent version.

​
Repository layout

  • Repository root: LICENSE, README.md
  • synheart-behavior/ (extension package)
    • manifest.json — Chrome MV3 manifest
    • background.js — Service worker (batch + send)
    • content.js — Behavioral capture
    • popup.html
    • src/popup.js, src/popup.css
    • icons/

​
Testing

Validate manifest and JavaScript syntax: 
node -e "JSON.parse(require('fs').readFileSync('synheart-behavior/manifest.json','utf8'))"
node --check synheart-behavior/background.js
node --check synheart-behavior/content.js
node --check synheart-behavior/src/popup.js
For manual verification, load unpacked from dist, open the Sensor tab, enable recording, and confirm events in your agent logs.

​
Resources

​
License

Licensed under the Apache License, Version 2.0.