CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
A macOS tool that imports camera cards to the Mac (SHA-256 verified), mirrors them to a USB
drive and uploads JPG/video to Google Photos via rclone. A local web dashboard and a menu-bar
app sit on top. Open work and its reasons are in scratch/ai_tasks.md (gitignored); read it
first when asked to “continue”. What only the user can do is in scratch/human_todo.md.
Commands
- Tests:
tools/test.sh full(about 1,200 tests, about 4 min) ortools/test.sh fast(about 35 s, withouttest_trigger,test_service_control,test_google_photos_processand the browser tests). Use the project.venv, not the systempython3, which has no Pillow. - Which tests when: only the affected modules while working;
fastbefore a commit that touches several areas;fullonce before a push; CI always runs everything. Changes to the shell scripts or the dashboard page need the slow modules they affect run directly. Run mutation checks in the background on a temp copy, never chained with a full run. - One module or test:
.venv/bin/python -m unittest tests.test_usb_backup, or add.TestBackupLauncher.test_request_runs_importer_when_lock_is_free. Filter by name with-k. - Browser tests:
.venv/bin/python -m unittest tests.browser.test_dashboard_page(about 45 s). They are part ofdiscoverand skip without Playwright’s Chromium (.venv/bin/python -m playwright install chromium). See “How the user likes to work” for screenshots. - Coverage:
.venv/bin/python -m coverage run -m unittest discover, thencoverage combineandcoverage report. CI fails belowfail_underin.coveragerc; raise it when tests are added. Shell scripts andweb/index.htmlaren’t measured. - Format:
.venv/bin/python -m ruff format .(CI runs it with--check). - Lint:
.venv/bin/python -m ruff check .. ruff enforces max complexity 15 (C901), so split functions instead of raising the limit. - Shell syntax:
bash -n install.sh uninstall.sh scripts/*.sh tools/*.sh. macOS ships bash 3.2, so use${arr[@]+"${arr[@]}"}for arrays that may be empty underset -u. - Python target is 3.9 (CI runs 3.9, 3.11, 3.13 and 3.14 on macOS).
How the pieces run
Separate processes that share files, not one app:
- launchd runs
scripts/trigger.sh(30 s poll plusWatchPathson/Volumes). It finds a volume withDCIMand useslaunchctl submitto startscripts/import_supervisor.sh, which runsbin/photo-offloader-import. - The importer writes
status.json(progress.py) and starts the Google sync in the background after a successful import. The sync writesgoogle_photos_status.json. - The dashboard and menu bar never copy files themselves. They show that state and the catalog,
and act by launching the
bin/andscripts/programs or touching marker files such as.paused.
Two consequences:
- The shell scripts can’t see
config.py. They repeat its paths and takePHOTO_OFFLOADER_*environment overrides, soisolate_configdoesn’t protect them. Tests of the scripts pass those variables instead (seetests/test_trigger.py). If a path changes, update both sides.trigger.shparsessettings.txt(settings.py) itself. - The archive folders and backup drive come from
settings.txtin the data folder (settings.py), applied byconfig.reload_settings(). Each program reads it as it starts; the dashboard and menu bar reload it while running. A file with a problem makes the copying programs refuse to run (config.check_settings()), never fall back silently. - A source checkout uses the real data. Only code paths follow
APP_ROOT; the archives, catalog andstatus.jsonalways resolve to the real locations. Runningbin/programs from the repo acts on the live install, and the dashboard also launches the installed programs (PHOTO_OFFLOADER_INSTALL_DIRredirects it).tests/browser/harness.pyruns the page against a sandbox.
Safety invariants
- Never delete from a card and never overwrite a destination file. A differing file with the
same name becomes
name__conflict-N. The one exception is the USB copy of an index file the camera rewrites (NC_FLLST.DAT,MEDIAPRO.XML); imports leave those files out. - The catalog and the card manifests are caches. The filesystem is the source of truth, and a
missing or stale cache must fall back to hashing. Both outlive a format, so a cached hash only
skips a file after
fileops.ends_matchagrees with the saved copy, unlesscard.card_is_intactshows the card wasn’t formatted, which only covers hashes from that card’s manifest. - Cards are read-only to this tool: nothing is ever written to one (macOS adds
.fseventsditself). - A USB or Google Photos failure never invalidates a verified local import.
- The trigger locks and the importer’s session lock overlap on purpose. Keep all of them.
Layout
photo_offloader/config.py: every path and setting. Code readsconfig.NAMEat call time, neverfrom config import NAME.- The importer is split into
card,media_info,transfer,run_report,catalog,fileops,volumes,progress,logsandcatalog_refresh;importeris only the command line. Imports only point downward. - Modules call each other qualified (
catalog.catalog_row(...)). Tests patch a name in the module that owns it. photo_offloader/jsonfile.py: tolerant reads and atomic writes of the JSON state files.photo_offloader/dashboard/:core.pyholds state and actions (unit-tested),display.pythe pure wording and cards,paths.pyits file locations,server.pyis the stdlib HTTP server (keep its token, Host/Origin and CSP checks),web/index.htmlis one static page that builds the DOM withtextContentonly and never puts card-derived text ininnerHTML.menubar/: puremodel.pyplus arumpsapp.photo_offloader/verify.py: rechecks saved copies against the catalog. It reports only and is a separate program, without the session lock orstatus.json, because the trigger and dashboard take a runningphoto-offloader-importto mean an import, and a check takes many minutes.verify_report.pyholds what it shares with the dashboard, which can’t import it: the saved report and the files someone has said they deleted from the Mac.bin/launchers,scripts/(trigger, import_supervisor, service),tools/,tests/.docs/holds the user documentation, one topic per page, linked from a shortREADME.md.- The root
index.htmlis the GitHub Pages landing page, not the dashboard page. It links todocs/and doesn’t repeat it. Pages builds the site frommainwith Jekyll, using_config.yml,_layouts/default.htmlandassets/site.css. The README is published asget-started.html. - The installed app (
~/Library/Application Support/PhotoOffloader) mirrors this layout.install.shcopiesbin/,scripts/andphoto_offloader/; new top-level files must be added there.
Rules that matter
- The app is installed and running on this Mac. Tests must never touch the real
install or data folders, start the real Google sync, or write the real
status.json. Usetests/support.isolate_config(self, tmp); it refuses to run ifconfiggains a path it doesn’t cover.- After changing fixtures, check:
touch m; run tests; find ~/Library/Application\ Support/PhotoOffloader* -type f -newer m ! -name '*-wal' ! -name '*-shm'. Empty output means no real file changed. The running service changes folder timestamps and the catalog’s-wal/-shmfiles, so the check leaves those out.
- After changing fixtures, check:
- Never run
install.shoruninstall.shyourself. They re-register the user’s real LaunchAgents. To check the installed layout, copybin scripts photo_offloader VERSIONto a temp dir and run the launchers from there. - Real data is read-only. Benchmark against a copy of the catalog made with the sqlite3 backup API, kept in the scratchpad. Read camera cards only.
- No new required runtime dependencies without asking. The dashboard is deliberately stdlib plus one static page.
How the user likes to work
- Write the failing test first, confirm it fails for the right reason, then fix. Mutation-check important fixes (break the code, make sure the test goes red).
- Base claims on measurements (logs, timings on real data), not guesses.
- Update
CHANGELOG.md([Unreleased]) anddocs/(orREADME.md) with behavior changes. - Commits in reviewable units: the message explains why, and behavior changes stay separate from moves and renames.
- Work on a branch from
mainand open a PR; merge with a merge commit (not squash). - Follow
CODE_QUALITY.mdfor clean code, reuse, errors, logging and ease of use. - UI preferences: a modern look, controls hidden until needed, one fixed-size transfer
panel for the whole run, nothing that flashes in or out. Check page changes with the
browser tests, and look at the result: set
PHOTO_OFFLOADER_TEST_SCREENSHOTS=<folder>and runtests.browser.test_dashboard_page.TestScreenshots. A new page state gets a scenario intests/browser/harness.py.