redshift-rebooted/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Redshift adjusts screen color temperature according to time of day using gamma ramps. The project consists of:

• redshift: C program that manages color temperature adjustment
• redshift-gtk: Python GUI wrapper providing a system tray status icon

Build System

This project uses GNU Autotools (autoconf/automake).

Building from Source

# Initial setup (only needed after git clone)
./bootstrap

# Configure with prefix for local development
./configure --prefix=$HOME/redshift/root \
  --with-systemduserunitdir=$HOME/.config/systemd/user

# Build
make

# Install to prefix directory
make install

# Run distribution checks
make distcheck

Platform-Specific Configuration

Linux (full features):

./configure --enable-drm --enable-vidmode --enable-randr --enable-geoclue2 --enable-gui --enable-apparmor

macOS:

./configure --enable-corelocation --enable-quartz --enable-gui

Windows (cross-compile with MinGW):

./configure --disable-drm --disable-randr --disable-vidmode --enable-wingdi \
  --disable-quartz --disable-geoclue2 --disable-corelocation --disable-gui \
  --disable-ubuntu --host=x86_64-w64-mingw32

Running Tests

# Basic functionality test
./root/bin/redshift -l 12:-34 -pv

# Test with dummy adjustment method
./root/bin/redshift -l 12:-34 -m dummy -vo

# Test with configuration file
echo -e "[redshift]\ndawn-time=6:30\ndusk-time=18:00-19:30" > test.config
./root/bin/redshift -c test.config -pv

Architecture

Core Components

Main Program (src/redshift.c):

• Entry point and main event loop
• Sets display gamma every few seconds/minutes based on solar calculations
• Handles SIGUSR1 (toggle day/night), SIGINT/SIGTERM (restore gamma and exit)
• Short transitions (~10s) at startup/signal; long transitions (~50min) otherwise

Adjustment Methods (gamma ramp manipulation):

• gamma-drm.c/h: DRM method for Linux TTY
• gamma-randr.c/h: RANDR method (preferred for X11, supports multiple outputs)
• gamma-vidmode.c/h: VidMode method (X11, older, single output)
• gamma-quartz.c/h: macOS Quartz
• gamma-w32gdi.c/h: Windows GDI
• gamma-dummy.c/h: No-op for testing

Location Providers (determine geographic coordinates):

• location-manual.c/h: Manual lat/lon specification
• location-geoclue2.c/h: Automatic location via GeoClue2 (Linux)
• location-corelocation.m/h: macOS CoreLocation (Objective-C)

Supporting Modules:

• solar.c/h: Solar position calculations for day/night timing
• colorramp.c/h: Color temperature to RGB gamma conversion
• config-ini.c/h: Configuration file parsing
• options.c/h: Command-line option handling
• hooks.c/h: Hook scripts for events
• signals.c/h: Unix signal handling
• systemtime.c/h: System time utilities

GUI Component

redshift-gtk (Python):

• Located in src/redshift-gtk/
• controller.py: Manages redshift subprocess
• statusicon.py: System tray icon
• utils.py: Utility functions
• Sends SIGUSR1 to redshift when user clicks icon

Conditional Compilation

Features are enabled/disabled via autoconf (configure.ac). The src/Makefile.am conditionally includes source files based on:

• ENABLE_DRM, ENABLE_RANDR, ENABLE_VIDMODE, ENABLE_QUARTZ, ENABLE_WINGDI
• ENABLE_GEOCLUE2, ENABLE_CORELOCATION
• ENABLE_GUI, ENABLE_UBUNTU, ENABLE_SYSTEMD, ENABLE_APPARMOR

C Coding Style (from CONTRIBUTING.md)

• Follow Linux kernel coding style
• Max 80 characters per line in new code
• All structures are typedef'd
• No Yoda conditions
• No multiline if-statements without braces (use single line or add braces)
• C-style comments only (/* */)

Dependencies

Build tools:

• autotools, gettext, intltool, libtool

Optional runtime (Linux):

• libdrm (DRM support)
• libxcb, libxcb-randr (RandR support)
• libX11, libXxf86vm (VidMode support)
• glib-2.0, gio-2.0 >= 2.26 (GeoClue2 support)

Optional GUI:

• python3 >= 3.2, pygobject, pyxdg
• appindicator (Ubuntu-style status icon)

See .travis.yml for Ubuntu package list.

Configuration

Configuration file location:

• Linux/macOS: ~/.config/redshift.conf
• Windows: %USERPROFILE%\AppData\Local\redshift.conf

Sample: redshift.conf.sample

Location Provider Syntax

Command-line location syntax: -l PROVIDER:OPTIONS

Special case: -l LAT:LON (parsed as manual provider when LAT is numeric)

Example: -l manual:lat=55:lon=12 is equivalent to -l 55:12

Longitudes in western hemisphere must be negative (e.g., New York: 41,-74)

Translation Updates

make update-po

Translations are managed via Launchpad Translations for Redshift.

Notes

• Verbose logging is controlled in redshift.c; all verbose messages should be written there
• Location providers are only queried at startup, not during runtime
• Gamma ramps are the mechanism for color adjustment; other applications (games, video players) may temporarily reset them
• Wayland and Mir are not supported; users should use desktop environment's built-in night light features (GNOME Night Light, KDE Night Color)