renich/chronicle: Autonomous workday telemetry harvester and context engine for Linux/Wayland

Autonomous developer telemetry harvester, workday activity aggregator, and AI context synthesizer for Linux.

GitLab Project Metadata:

Description: Autonomous developer telemetry harvester, workday activity aggregator, and AI context synthesizer for Linux.

Topics / Tags: crystal, crystal-lang, telemetry, time-tracking, wayland, niri, gnome, ai-context, git, sqlite, agplv3

Overview

Chronicle bridges the gap between daily software engineering activity and actionable strategic intelligence. Designed for senior developers, engineering leads, and autonomous AI agents (such as Antigravity), Chronicle silently and passively collects high-fidelity telemetry across desktop windows, shell sessions, and Git repositories—without cloud dependencies, surveillance lock-in, or performance penalties.

Key Capabilities

Desktop Window Focus Tracking:
- Niri Compositor: Native JSON stream ingestion (niri msg -j event-stream).
- GNOME Shell (Wayland/X11): Multi-tier resolution supporting the FocusedWindow extension (Tier 1), WindowCalls extension (Tier 2), AT-SPI2 accessibility bus focus streaming (Tier 3), and XWayland xprop (Tier 4).
- Idle Partitioning: Filters lock screens and inactivity to ensure focus metrics reflect actual active work.
Shell Command Telemetry:
- Captures terminal commands, working directories ($PWD), exit statuses, and execution timestamps via a lightweight UNIX domain socket (/run/user/$UID/chronicle.sock).
Single-Pass Git Churn & Conventional Commits:
- Traverses local repositories for authored commits across configurable timeframes (today, yesterday, this week, or custom date ranges).
- Computes exact line churn (+insertions / -deletions) and categorizes changes according to Conventional Commits (feat, fix, docs, chore, refactor, test).
Project Journal & Architecture Synthesis (PJP):
- Scans .agents/journal entries written by ajourn to extract architectural decisions (DEC:), discoveries, and gotchas (GOT:), linking what changed to why it changed.
Deep-Work Session Clustering:
- Reconstructs continuous, multi-minute focus intervals and Git sprints to visualize flow state versus context switching.
Multi-Format Exporters:
- Console Report (chronicle report): Human-readable terminal digest for standups and retrospectives.
- Markdown AI Digest (chronicle export -f md): Ground-truth prompt context for LLM agents synthesizing weekly dispatches and sprint retrospectives.
- Structured JSON (chronicle export -f json): Clean programmatic telemetry for metrics pipelines.
- Scoping & Compact Modes: Scope reports to a specific workspace (-p <project>) or generate token-efficient summaries (-c / --compact).

Quickstart

Prerequisites

Crystal: >= 1.21.0
Shards: Bundled with Crystal
GNU Make & Git
SQLite3 development headers
Podman (optional, for rootless container builds)

Installation

# 1. Clone repository
git clone https://gitlab.com/renich/chronicle.git
cd chronicle

# 2. Install dependencies, hooks, and build binary
make setup
make build

# 3. Install release binary to ~/.local/bin/chronicle
make install-local

Running the Telemetry Daemon

Chronicle runs as a lightweight user background daemon:

# Run interactively in the foreground
chronicle daemon --log-level DEBUG

# Or install as a systemd user service:
# ~/.config/systemd/user/chronicle.service
systemctl --user daemon-reload
systemctl --user enable --now chronicle.service

CLI Usage & Examples

Workday Summary Report

# View today's activity
chronicle report

# View yesterday's activity
chronicle report --yesterday

# View current week's telemetry
chronicle report --this-week

# Scope to a specific repository
chronicle report -p chronicle

# Compact summary mode (optimized for quick glances or terminal status lines)
chronicle report -c --this-week

Example Report Output

══════════════════════════════════════════════════════════════════════
 Chronicle Workday Report: This Week (2026-09-14 - 2026-09-20)
══════════════════════════════════════════════════════════════════════

 Productivity Overview:
   Active Focus:   28.4 hours
   Idle / Away:    12.1 hours
   Deep Sessions:  42
   Shell Commands: 819
   Git Commits:    326 (+84210/-41205 lines)

 Project Time & Activity Breakdown:
   • sysrq              14.20 hrs (412 cmds, 128 commits +42150/-18200)
   • ofelia              8.50 hrs (230 cmds,  94 commits +28140/-14900)
   • chronicle           4.20 hrs (142 cmds,  78 commits +11420/-6805)
   • evalinux            1.50 hrs ( 35 cmds,  26 commits  +2500/-1300)

 Deep-Work Sessions Timeline:
   • 09:15 - 11:45  (2.50 hrs)  sysrq       [Code] (42 commits)
   • 13:00 - 15:30  (2.50 hrs)  ofelia      [Code] (31 commits)
   • 16:10 - 18:00  (1.83 hrs)  chronicle   [Code] (28 commits)

 Commits Distribution:
   feat: 184, fix: 76, docs: 38, chore: 28
══════════════════════════════════════════════════════════════════════

AI Context Export

Generate ground-truth prompt context for LLM agents:

# Export full Markdown telemetry digest
chronicle export -f md --this-week

# Export compact Markdown digest for prompt-constrained sessions
chronicle export -f md -c --today

# Export machine-readable JSON
chronicle export -f json --this-week

Build System Targets

The repository includes a strict GNU-compliant GNUmakefile:

Target	Description
`make build`	Compiles development binary in `bin/chronicle`
`make release`	Compiles optimized, stripped production binary
`make test`	Executes spec test suite (`crystal spec`)
`make lint`	Runs Ameba static analysis and Flaw SAST scanner
`make doc-check`	Lints all reStructuredText files using `crstlint` and `rstcheck`
`make check`	Full test, lint, and documentation verification pipeline
`make install-local`	Installs release binary directly to `~/.local/bin/chronicle`
`make install`	Installs binary to `$(DESTDIR)$(bindir)` (FHS compliant)
`make containers-build`	Builds rootless container image via Podman
`make clean`	Removes build artifacts
`make distclean`	Removes dependencies, caches, and build outputs

Documentation

Comprehensive architectural blueprints and specifications are maintained under docs/:

Guide	Scope & Highlights	Entry Point
Business Context & Strategy	Problem statement, ROI objectives, and user personas.	Business Specs
Functional Specifications	Requirements [FUNC-001]–[FUNC-010] and data harvesting contracts.	Functional Specs
Technical Architecture	Multi-tier desktop drivers, database schema, and threat model.	Technical Specs
User Guide	Operational setup, systemd units, and reporting tutorials.	Getting Started
Architecture Decisions (ADRs)	Architectural Decision Records and trade-off analyses.	ADR Index
Release Playbook	SemVer, Keep a Changelog, and GPG-signed GitLab release steps.	Release Procedure