> ## 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.

# Synheart Sensor Agent Overview

> Privacy-first PC background sensor for behavioral research from keyboard and mouse interactions

## 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 Capture                                      | What 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```text theme={null}
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:

```json theme={null}
{
  "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

```text theme={null}
┌─────────────────────────────────────────────────────────────┐
│                    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

* **GitHub**: [synheart-ai/synheart-sensor-agent](https://github.com/synheart-ai/synheart-sensor-agent)
* **crates.io**: [synheart-sensor-agent](https://crates.io/crates/synheart-sensor-agent)
* **docs.rs**: [synheart-sensor-agent](https://docs.rs/synheart-sensor-agent)

## License

Licensed under the **Apache License, Version 2.0**.