Skip to main content

​
What is Synheart Sensor Agent?

Synheart Sensor Agent is a privacy-first PC background sensor that captures keyboard and mouse interaction timing (not content) for behavioral research. It extracts features like typing rhythm, mouse movement patterns, and interaction continuity - all without ever capturing what you type or where you click.

​
Key Features

  • Privacy by Design: Never captures key content, passwords, or screen coordinates
  • Behavioral Features: Extracts 16+ behavioral signals from interaction patterns
  • HSI Format: Exports data in the Human State Interface (HSI) JSON format (via Synheart Flux)
  • Transparency: Full visibility into what data is collected via status command
  • macOS Support: Native integration using Core Graphics event taps

​
Privacy Guarantees

What We CaptureWhat We Never Capture
When keys are pressed (timing only)Which keys you press (no passwords, messages, etc.)
How fast the mouse moves (speed only)Where your cursor is (no screen position tracking)
When clicks and scrolls occur (timing only)What applications you use
Any screen content

​
Installation

​
From Source

# Clone the repository
git clone https://github.com/synheart-ai/synheart-sensor-agent.git
cd synheart-sensor-agent

# Build in release mode
cargo build --release

# The binary will be at target/release/synheart-sensor

​
Requirements

  • Rust: 1.70 or later
  • macOS: 10.15 (Catalina) or later
  • Permissions: Input Monitoring permission required

​
Usage

​
Grant Input Monitoring Permission

Before the agent can capture events:
  1. Open System Preferences > Security & Privacy > Privacy
  2. Select Input Monitoring in the left sidebar
  3. Click the lock icon and authenticate
  4. Add the synheart-sensor application
  5. Restart the application

​
Commands

# Start capturing behavioral data
synheart-sensor start

# Start with specific sources
synheart-sensor start --sources keyboard
synheart-sensor start --sources mouse
synheart-sensor start --sources keyboard,mouse

# Pause collection
synheart-sensor pause

# Resume collection
synheart-sensor resume

# Show current status and statistics
synheart-sensor status

# Display privacy declaration
synheart-sensor privacy

# Export collected data
synheart-sensor export
synheart-sensor export --output /path/to/export --format jsonl

# Show configuration
synheart-sensor config

​
Core Gateway Integration

For real-time HSI processing via synheart-core-gateway, enable the gateway feature: 
# Build with gateway support
cargo build --release --features gateway

# Start with gateway sync (auto-detects port/token from runtime dir)
./target/release/synheart-sensor start --gateway

# Or specify port and token manually
./target/release/synheart-sensor start --gateway --gateway-port 8080 --gateway-token your-token

# Customize sync interval (default: 10 seconds)
./target/release/synheart-sensor start --gateway --sync-interval 5

​
Synheart Flux Integration

For rolling baselines and enriched HSI metrics, enable the optional flux feature: 
cargo build --release --features flux
./target/release/synheart-sensor start --flux
Enable both gateway sync and local flux processing: 
cargo build --release --features "gateway,flux"
./target/release/synheart-sensor start --gateway --flux

​
Behavioral Features

​
Keyboard Features

FeatureDescription
typing_rateKeys pressed per second
pause_countNumber of pauses (gaps > 500ms)
mean_pause_msAverage pause duration
latency_variabilityStd dev of inter-key intervals
hold_time_meanAverage key hold duration
burst_indexBurstiness of typing (0-1)
session_continuityActive typing ratio
typing_cadence_stabilityRhythmic consistency of typing (0-1)
typing_gap_ratioProportion of inter-tap intervals as gaps
typing_interaction_intensityComposite of speed, stability, gap behavior

​
Mouse Features

FeatureDescription
mouse_activity_rateMovement events per second
mean_velocityAverage cursor speed
velocity_variabilityConsistency of movement
acceleration_spikesSudden speed changes
click_rateClicks per second
scroll_rateScroll events per second
idle_ratioIdle vs active time
micro_adjustment_ratioSmall movements ratio

​
Derived Signals

SignalDescription
interaction_rhythmOverall input regularity
frictionHesitation/correction indicator
motor_stabilityMovement consistency
focus_continuity_proxySustained attention indicator
burstinessWhether interactions occur in clusters or evenly
deep_focus_blockTrue if window shows sustained, uninterrupted activity

​
Flux-Enriched Metrics (Optional)

When the --flux flag is enabled:
MetricDescription
distraction_scoreAggregate estimate of distraction
focus_hintAggregate estimate of focus
interaction_intensityFlux-computed interaction intensity

​
HSI Output Format

The agent exports data in HSI 1.0 (Human State Interface) JSON format: 
{
  "hsi_version": "1.0",
  "observed_at_utc": "2024-01-15T14:32:10+00:00",
  "computed_at_utc": "2024-01-15T14:32:10+00:00",
  "producer": {
    "name": "synheart-sensor-agent",
    "version": "0.1.0",
    "instance_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "axes": {
    "behavior": {
      "readings": [
        { "axis": "typing_rate", "score": 0.45, "confidence": 0.85 },
        { "axis": "typing_burstiness", "score": 0.65, "confidence": 0.85 },
        { "axis": "session_continuity", "score": 0.82, "confidence": 0.85 },
        { "axis": "focus_continuity", "score": 0.79, "confidence": 0.85 }
      ]
    }
  },
  "privacy": {
    "contains_pii": false,
    "notes": "No key content or coordinates captured - timing and magnitude only"
  }
}

​
Configuration

Configuration is stored at:
  • macOS: ~/Library/Application Support/synheart-sensor-agent/config.json
Default configuration: 
{
  "window_duration": 10,
  "sources": {
    "keyboard": true,
    "mouse": true
  },
  "paused": false,
  "session_gap_threshold_secs": 300
}

​
Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        Synheart Sensor Agent                            │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐                    │
│  │  Collector  │──▶│  Windowing  │──▶│  Features   │                    │
│  │   (macOS)   │   │  (10s bins) │   │ (compute)   │                    │
│  └─────────────┘   └─────────────┘   └─────────────┘                    │
│         │                                    │                           │
│         ▼                                    ▼                           │
│  ┌─────────────┐                     ┌─────────────┐   ┌─────────────┐  │
│  │Transparency │                     │    HSI      │──▶│   Gateway   │  │
│  │    Log      │                     │  Snapshot   │   │   Client    │  │
│  └─────────────┘                     └─────────────┘   └─────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

​
Troubleshooting

​
”Input Monitoring permission not granted”

  1. Open System Preferences > Security & Privacy > Privacy
  2. Select Input Monitoring
  3. Ensure the application is in the list and checked
  4. If already checked, remove and re-add the application
  5. Restart the application

​
No events being captured

  • Ensure you’re actively typing or moving the mouse
  • Check that the correct sources are enabled (--sources all)
  • Verify permission is granted with synheart-sensor status

​
Resources

​
License

Licensed under the Apache License, Version 2.0.