ClackHouse Agent

ClackHouse Agent is a local-first, privacy-preserving typing analytics agent for macOS and Linux. It converts keyboard activity into aggregated metrics, session rollups, and app-context signals without exporting typed content.

Privacy Boundary

The agent never exports:

• raw typed text
• raw key sequences
• raw per-keystroke timelines

The agent can export:

• aggregated typing buckets
• completed session rollups
• app-context switch events
• device snapshots

Everything that crosses the export boundary is intentionally lossy, aggregated, and configurable. See the config reference and export contracts.

Quickstart

Start from the sample config and place it at the default runtime path:

mkdir -p ~/.clackhouse
cp config.example.yaml ~/.clackhouse/config.yaml

If ~/.clackhouse/config.yaml is absent, the agent falls back to built-in defaults: runtime state stays under ~/.clackhouse, no typing-data sinks are configured, and anonymous usage telemetry remains enabled.

Then configure at least one sink and either run the agent directly:

clackhouse-agent run

or install it as a background service:

clackhouse-agent service install
clackhouse-agent service start
clackhouse-agent status

Direct runs stay attached to the current process. Installed services are managed by a per-user LaunchAgent on macOS and systemd --user on Linux.

Documentation

• Docs home
• Getting started
• Config reference
• Export contracts
• Maintainer notes

Development

Maintainer notes live in docs/maintainers.md. The short version:

just check
just run
just install-hooks

Release history is tracked in CHANGELOG.md.

License

Licensed under Apache-2.0.