Chronicle is a privacy-focused Linux screen timeline tool that captures periodic screenshots and syncs them to your self-hosted Immich instance. It is designed for long-running personal activity timelines with secure credential handling, resilient local queueing, and automation-friendly CLI workflows.

Features

• Periodic screenshot capture with configurable interval and monitor selection.
• Multiple Linux capture backends:
  • Wayland native capture via grim (when available)
  • XDG portal fallback via xdg-desktop-portal
  • X11 fallback via scrot
• Adaptive capture mode to skip near-identical frames and reduce storage usage.
• Background upload queue with retry logic and manual upload trigger.
• Immich integration (server URL + API key + optional album targeting).
• Secure API key support via system keyring, with env/config fallbacks.
• Systemd user service installation (chronicle-capture.service, chronicle-upload.timer).
• Interactive setup wizard with resumable progress.
• Rich CLI surface for status, health, pause/resume, tags, and config management.
• JSON output modes for scripting (status --json, health --json, upload --json, etc.).

Getting Started

Prerequisites

Required

• Linux (Wayland or X11 session)
• A running Immich server and an Immich API key

Runtime tools (capture backends)

Install at least one backend appropriate for your session:

• Wayland preferred: grim
• Portal fallback: xdg-desktop-portal (+ compositor/desktop portal backend)
• X11 fallback: scrot

System integration

• systemd --user (used for background capture/upload services and installed during setup)
• A desktop keyring service (for secure API key storage)

Installation

Install Chronicle from the Releases page.

Debian/Ubuntu

1. Download the latest .deb from Releases.
2. Install it:

sudo apt install ./chronicle_<version>_amd64.deb

If your system does not resolve dependencies automatically:

sudo dpkg -i ./chronicle_<version>_amd64.deb
sudo apt install -f

Verify installation

chronicle --help
chronicle setup

Runtime dependencies

These are mainly relevant for native installs (.deb or source builds).

Example for Debian/Ubuntu (adjust for your distro):

sudo apt update
sudo apt install -y grim scrot xdg-desktop-portal

On GNOME/KDE/Sway you may also need the corresponding portal backend package (for example xdg-desktop-portal-gnome, xdg-desktop-portal-kde, or xdg-desktop-portal-wlr).

Build from source

Only needed if you are developing Chronicle locally.

Source prerequisites

• Rust toolchain (stable, Rust 1.85+)
• Cargo

Source install

git clone https://code.marvil.co/jorge/chronicle.git
cd chronicle
cargo build --release && cargo install --path .
chronicle setup

The wizard configures server URL, API key storage, capture/upload behavior, metadata options, and installs the background systemd user services.

Usage

Common workflow

# Start Chronicle in the background
chronicle start

# Run in the foreground for debugging
chronicle start --foreground

# Check live state
chronicle status
chronicle health

# Pause capture for 1 hour and 30 minutes
chronicle pause 1h30m

# Resume capture
chronicle resume

# Trigger manual upload (chronicle must be running)
chronicle upload

# Stop daemon
chronicle stop

Setup and authentication

# Guided setup (resume if interrupted)
chronicle setup
chronicle setup --resume

# Manage API credentials
chronicle auth set
chronicle auth status
chronicle auth test
chronicle auth clear

Configuration management

# Show resolved config
chronicle config show

# Read/set keys
chronicle config get capture.interval_seconds
chronicle config set capture.interval_seconds 30

# Validate config file
chronicle config-validate
chronicle config-validate --json

# Edit and reload
chronicle config edit
chronicle config reload

Automation-friendly JSON output

chronicle status --json
chronicle health --json
chronicle upload --dry-run --json

Session tagging

# Set active tags for future captures
chronicle tag work

# Show current tags
chronicle tag --show

# Clear tags
chronicle tag --clear

Systemd user services

chronicle start prefers the installed user service when available. Otherwise it launches a detached background process.

# Install + enable services/timer
chronicle install --enable

# Uninstall services
chronicle uninstall

# Inspect units
systemctl --user status chronicle-capture.service
systemctl --user status chronicle-upload.timer

Configuration

Primary config file lives at:

• ~/.config/chronicle/config.toml

Contributing

Contributions are welcome. The source is in a private Forgejo server, but there is a public mirror on Codeberg for easier contributor access.

Recommended local checks:

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test