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.

​
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
  • Transparency: Full visibility into what data is collected via status command
  • App Context: Captures foreground application bundle ID per window for task-switch detection (no window titles or content)
  • macOS Support: Native integration using Core Graphics event taps
  • Windows Support: Native integration using Windows Hooks API

​
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)Window titles or application content
Foreground app bundle ID (for task-switch detection)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.82 or later
  • macOS: 10.15 (Catalina) or later
  • Windows: 10 or later
  • Permissions: Input Monitoring (macOS) or Run as Administrator (Windows)

​
Usage

​
Grant Input Capture Permission

​
macOS

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

​
Windows

Run the sensor agent as Administrator to capture input events:
  1. Right-click the synheart-sensor.exe binary
  2. Select Run as administrator
  3. Or launch your terminal (Command Prompt / PowerShell) as Administrator before running the binary

​
Commands

# Start capturing behavioral data (default: --sources all)
synheart-sensor start

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

# Pause / resume collection
synheart-sensor pause
synheart-sensor resume

# Show current status and statistics
synheart-sensor status

# Display privacy declaration
synheart-sensor privacy

# Show resolved configuration
synheart-sensor config

# Run as an HTTP server (feature-gated; requires `--features server` build)
synheart-sensor serve

​
Data Flow

The sensor-agent is a pure collector. It captures raw keyboard/mouse timing events and exposes them. Feature extraction, windowing, and session management are handled by the Synheart Runtime: 
sensor-agent (raw events) --> Synheart runtime (SensorTranslator → FeatureSet)

​
Configuration

Configuration is stored at:
  • macOS: ~/Library/Application Support/synheart-sensor-agent/config.json
  • Windows: %APPDATA%\synheart-sensor-agent\config.json
Default configuration: 
{
  "sources": {
    "keyboard": true,
    "mouse": true
  },
  "data_path": "~/.local/share/synheart-sensor-agent",
  "paused": false
}
data_path is the directory where the transparency log is written.

​
Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Synheart Sensor Agent                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐                     ┌─────────────┐       │
│  │  Collector  │────────────────────▶│ Raw Events  │       │
│  │   (macOS)   │                     │  (channel)  │       │
│  └─────────────┘                     └─────────────┘       │
│         │                                                  │
│         ▼                                                  │
│  ┌─────────────┐                                           │
│  │Transparency │                                           │
│  │    Log      │                                           │
│  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────┘
         Pure sensor — windowing, features, and sessions handled
         by the Synheart Runtime

​
Troubleshooting

​
macOS: “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

​
Windows: “Administrator privileges required”

  1. Right-click the terminal or binary and select “Run as administrator”
  2. If using PowerShell, launch it with elevated privileges
  3. 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
  • macOS: Confirm Input Monitoring permission in System Preferences
  • Windows: Confirm the process is running as Administrator

​
Resources

​
License

Licensed under the Apache License, Version 2.0.