Chronicle v0.1.0: Telemetry harvester and context engine for Wayland and AI agents

News
1

Hello everyone,

I’ve tagged the initial v0.1.0 release of Chronicle, a local, privacy-first telemetry daemon and context correlation engine written in Crystal.

The Problem

When pair programming with AI agents or conducting weekly engineering retrospectives, human engineers and autonomous agents often lose high-resolution context regarding what was worked on across disparate repositories, terminal tabs, and editor windows. Existing commercial solutions either exfiltrate activity to third-party clouds or lack the correlation depth required by LLMs to reconstruct technical progress.

What Chronicle Does

Chronicle runs as a non-blocking local daemon (via systemd user service) and collects lightweight, local-only telemetry:

  1. Compositor Window Focus: Subscribes directly to Wayland IPC streams. Native drivers currently exist for Niri (niri msg -j event-stream), Sway (i3 IPC), and KWin (via qdbus), along with Wayland idle state detection.
  2. Shell History Harvester: Ingests commands executed across Bash, Zsh, and Fish, mapping them to current working directories.
  3. Git Churn & Conventional Commits: Scans local git repositories in a single-pass git log run, extracting files changed, insertions, deletions (--shortstat), and classifying commits via Conventional Commits metadata.
  4. Project Attribution Engine: Correlates window focus duration, shell commands, and git churn into discrete project workspaces.
  5. Deep-Work Session Clustering: Groups contiguous focus intervals into discrete work sessions based on a configurable idle threshold (default 15 minutes).
  6. Multi-Format Exporters:
    • chronicle report --today: Human-readable terminal dashboard.
    • chronicle export -f md --compact: Token-efficient Markdown summary optimized for LLM context injection.
    • chronicle export -f json: Structured machine telemetry.
    • Scoping via --project <name> (-p).

Why Crystal?

Chronicle relies on Crystal’s concurrency model (Execution Contexts and lightweight fibers) to process IPC event streams concurrently with local SQLite3 writes without perceptible latency or CPU overhead. A single stripped native binary runs rootless with zero JVM/Node dependencies.

Links

Feedback and patches are welcome.