# CLAUDE.md — hyprsunset-qt

PyQt6 GUI to edit `~/.config/hypr/hyprsunset.conf`, fetch sunrise/sunset times
for the user's location, and restart the `hyprsunset` daemon.

## Layout

- `hyprsunset_qt/config.py` — `Profile` dataclass, parse/serialize
  hyprsunset.conf, read/write, `day_index`/`night_index` detection, field
  validators. Pure logic, no Qt/network.
- `hyprsunset_qt/settings.py` — `Settings` (INI at `~/.config/hyprsunset-qt/config`).
- `hyprsunset_qt/sun.py` — geolocate (ip-api.com), fetch_sun
  (sunrise-sunset.org), UTC→local `HH:MM`, JSON cache read/write.
- `hyprsunset_qt/daemon.py` — `is_running`/`restart`/`live_preview`, all
  subprocess shell-outs (pgrep, pkill, hyprctl).
- `hyprsunset_qt/ui.py` — `ProfileRow` + `MainWindow`. Only module importing PyQt6.
- `hyprsunset_qt/__main__.py` — entry point (`python3 -m hyprsunset_qt`).
- `tests/` — pytest for the pure-logic modules only.
- `docs/superpowers/` — design spec + implementation plan.

## Key facts

- **Config vs settings are two files.** `hyprsunset.conf` (the daemon's, in
  `~/.config/hypr/`) is regenerated clean on save — hand comments/whitespace
  are lost, day/night comments emitted. App settings live separately in
  `~/.config/hyprsunset-qt/config`.
- **Cache in `~/.config`, not `~/.cache`** — the user's `~/.cache` is wiped at
  reboot. Sunset JSON cache refreshes on manual Fetch only.
- **day/night is inferred, not stored**: day = first profile with
  `identity=true`, night = first with `temperature` set. Sunrise→day time,
  sunset→night time.
- **hyprsunset v0.3.3 has no config reload** — applying config = kill+relaunch
  (`pkill hyprsunset` then launch). IPC (`hyprctl hyprsunset temperature|gamma|
  identity`) is live-preview only; gamma float 0–2 maps to integer percent.
- Deps: PyQt6 + stdlib only. Minimal-deps rule.

## Workflow

- Tests: `python3 -m pytest -q`. Qt/network/daemon layers are thin wrappers,
  not unit-tested (mocked or manual). TDD for pure logic.
- Commits: GPG-signed (`git commit -S`). Work on master.
- License: GPLv2-only, per-file header present.

## Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.