Climate Advisor for Home Assistant

An intelligent HVAC management integration that uses weather forecasts, occupancy, and door/window sensors to minimize energy waste while keeping your home comfortable — and learns from your household's behavior over time.

Temperature Forecast	Current Status

24-hour View (prediction accuracy)	AI Investigative Analysis

┌──────────────────────────────────────────────────────────────┐
│                      Climate Advisor                         │
│                                                              │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────┐        │
│  │  Classifier │─▶│  Coordinator │◀──│  Learning   │        │
│  │             │   │   (brain)    │   │  Engine     │        │
│  │ • Day type  │   │              │   │             │        │
│  │ • Trend     │   │ • Scheduling │   │ • Tracking  │        │
│  │ • Forecast  │   │ • Briefings  │   │ • Patterns  │        │
│  │   analysis  │   │ • Events     │   │ • Suggest   │        │
│  └─────────────┘   └──────┬───────┘   └─────────────┘        │
│                           │                                  │
│        ┌──────────┬───────┼───────┬──────────┐               │
│        ▼          ▼       ▼       ▼          ▼               │
│  ┌──────────┐ ┌────────┐ ┌─────┐ ┌────────┐ ┌─────────┐      │
│  │Automation│ │Briefing│ │ API │ │Sensors │ │ State   │      │
│  │ Engine   │ │  Gen   │ │     │ │ (18x)  │ │Persist  │      │
│  │          │ │        │ │22   │ │+ 1     │ │         │      │
│  │• HVAC    │ │• Daily │ │REST │ │switch  │ │• Save / │      │
│  │• Door/win│ │  email │ │end- │ │        │ │  restore│      │
│  │• Occupy  │ │• TLDR  │ │point│ │• Status│ │  across │      │
│  │• Fan ctrl│ │• Tips  │ │s    │ │• Learn │ │  restart│      │
│  │• Econom. │ │        │ │     │ │• Fan   │ │         │      │
│  └──────────┘ └────────┘ └─────┘ └────────┘ └─────────┘      │
└──────────────────────────────────────────────────────────────┘
         │            │         │         │
         ▼            ▼         ▼         ▼
   HA Climate    HA Notify   Dashboard  HA Dashboard
   Entity        Service     Panel      Lovelace Cards

1. 6:00 AM — Coordinator pulls forecast, classifies the day, and sends the daily briefing email/notification
2. 6:30 AM — Morning warm-up restores comfort setpoint
3. Throughout the day — Automation engine responds to doors, windows, occupancy, and temperature changes. CA programs a target comfort band [comfort_heat / comfort_cool] and the thermostat's own deadband maintains it — every command is a single heat or cool setpoint, not a dual-setpoint hold.
4. 10:30 PM — Bedtime setback kicks in
5. 11:59 PM — Day's data is saved to the learning engine

The forecast trend (tomorrow vs. today) adjusts behavior:

• Warming 10°F+: More aggressive overnight setback (tomorrow's warmth will help)
• Warming 5-10°F: Moderate setback increase
• Cooling 5-10°F: Pre-heat in evening, gentler setback
• Cooling 10°F+: Significant pre-heat, conservative setback, bank thermal energy

Climate Advisor tracks occupancy state via configurable toggle entities:

Supports whole-house fan and/or HVAC fan mode integration:

• Whole-house fan: Controls a dedicated fan entity (switch or fan domain) during economizer maintain phase. While the whole-house fan is active, CA sets the thermostat off so AC and the fan do not run simultaneously; prior mode is restored when the fan stops.
• HVAC fan mode: Activates your thermostat's fan-only mode for ventilation
• Both: Coordinates both fan types together
• Dual-entity WHF support: An optional separate fan_state_entity lets CA read ground-truth physical state independently of the command entity (Type 2 installations)
• Command-only mode (fan_state_feedback off, default): CA asserts the desired fan state idempotently without reading back entity state, avoiding false override detection on command-echo entities. Turn on fan_state_feedback for installations with a dedicated state sensor.
• Integrated with the economizer two-phase cooling strategy (cool-down with AC, maintain with ventilation)
• QuietCool RF remote timer support (optional, fan_remote_entity): if you flash your QuietCool whole-house fan's ESP32 controller with the gunkl/quietcool-house-fan firmware, CA can hear physical wall-remote timer presses (1/2/4/8/12 hours) via an HA event entity and honor them as the fan's manual-override grace duration — see docs/fan-remote-spec.md (Issue #486). Leave the field blank if you don't use this hardware; nothing changes.

After 14+ days of data, the learning engine starts analyzing patterns:

• Window compliance: If you rarely open windows when recommended, it offers to switch to HVAC-only strategies
• Manual overrides: Frequent thermostat adjustments suggest setpoints don't match preferences
• Runtime anomalies: High HVAC runtime on mild days may indicate sensor gaps
• Short departures: Adapts setback timing if you frequently leave for 30-45 minutes
• Comfort violations: Suggests less aggressive setbacks if the house is uncomfortable too often
• Door pauses: Identifies problem doors and offers to adjust monitoring

Climate Advisor includes one Claude-powered AI capability, requiring a Claude API key in settings:

AI Investigator (ai_investigator_enabled) — performs deep cross-source analysis to detect incongruities between the thermal model, pipeline statistics, compliance data, and event log. Returns hypotheses with confidence levels and recommended actions. Context is assembled from independently-testable provider functions with focus-aware selection — specifying a focus keyword (thermal, fan, nat-vent, etc.) skips irrelevant providers and reduces token usage. Results stream over SSE, so text appears within a few seconds instead of waiting for the full report. GitHub issue history used for known-fix matching is cached (24h open / 30d closed) to avoid a live API call on every run. Results appear in the Investigation panel on the Analysis tab, where findings can be submitted directly as GitHub issues (requires GitHub token configured under Settings → GitHub Integration).

Activity Record — a deterministic (non-AI) event timeline with indoor/outdoor temperature at each decision point. Available alongside the AI Investigator report on the Analysis tab; no API key required. (The separate, Claude-powered "AI Activity Report" skill was retired in Issue #578 — it had not written new data since being merged into the AI Investigator in Issue #563, and is superseded by this deterministic report.)

Separate sleep_heat and sleep_cool setpoints can be configured to define bedtime comfort targets that are distinct from the away setback temperatures. This allows a warmer-than-setback but cooler-than-daytime sleep environment without conflating bedtime comfort with absence setback.

The natural ventilation directional guard prevents counterproductive ventilation: nat vent activation is blocked when outdoor temperature would move indoor temperature in the wrong direction. A hysteresis band and reactivation lockout prevent rapid cycling. The guard also preserves an active nat vent session through HVAC-off classification events so natural cooling is not prematurely cancelled.

Nat-vent can continue past bedtime when outdoor air is still below the sleep target — free cooling closes the gap before handing off to the compressor, cycling off at sleep_heat and back on at sleep_heat + 2×hysteresis to avoid over-cooling. Fan status is tracked as a distinct ON/OFF state machine so nat-vent adoption, setpoint-echo suppression, and post-grace reconciliation are all handled without false override detection.

The thermal model uses a physics ODE to characterize how the house envelope and HVAC system move indoor temperature over time:

dT/dt = (k_passive + k_vent_eff) × (T_out − T_in) + k_solar × solar_factor + Q_hvac

Six parallel observation types run concurrently, each targeting a different thermal parameter:

Parameters are extracted via OLS regression over the full decay or active-phase curve — not from a single start/end delta. Confidence levels (none / low / medium / high) are tracked per parameter independently. Physics-based prediction activates when any parameter has confidence above none, so homes without HVAC cycles can still benefit from passive decay observations. The predicted indoor curve in the dashboard uses all available parameters.

1. Open HACS in Home Assistant
2. Click the three dots → Custom repositories
3. Add https://github.com/gunkl/ClimateAdvisor as an Integration
4. Search for "Climate Advisor" and install
5. Restart Home Assistant
6. Go to Settings → Integrations → Add Integration → Climate Advisor

1. Copy the custom_components/climate_advisor folder to your HA config/custom_components/ directory
2. Restart Home Assistant
3. Go to Settings → Integrations → Add Integration → Climate Advisor

The setup wizard walks you through these steps:

• Weather Entity: Your forecast provider (e.g., weather.home)
• Climate Entity: Your thermostat (e.g., climate.living_room)
• Notification Service: Where to send briefings (e.g., notify.mobile_app_phone)

Choose Fahrenheit or Celsius. This setting controls all displayed values and setpoint inputs throughout the integration.

Separate comfort and setback temperatures for heating and cooling, plus optional sleep_heat / sleep_cool bedtime setpoints.

Choose where indoor and outdoor temperature readings come from:

• Weather service (recommended for outdoor)
• Dedicated sensor entity
• Input number helper
• Climate entity fallback (indoor only)

• Select any binary sensors to monitor (HVAC pauses when open)
• Configure sensor polarity (for inverted sensors)
• Set debounce time (default 5 minutes) and grace periods
• Fan control: Choose fan mode (disabled, whole-house fan, HVAC fan, or both) and select fan entity

• Home/away toggle entity (optional)
• Vacation toggle entity (optional)
• Guest toggle entity (optional)
• Polarity inversion for each toggle

Set your wake time, bedtime, and when you want the daily briefing.

Climate Advisor acts as the scheduler — the thermostat is the executor. For reliable operation, your thermostat must be configured so that CA's commands are held exactly as sent:

1. Disable built-in schedules and comfort programs — Turn off any manufacturer-defined schedules, comfort programs, or "Smart Home/Away" features. If the thermostat applies its own schedule after CA sets a setpoint, the physical device will silently revert to its own values even though HA still shows CA's last command.

2. Set hold type to "Hold until I change" (indefinite hold) — Many thermostats default to "hold until next scheduled transition," which means the thermostat reverts to its comfort program at the next scheduled event (e.g., 8 am "Home" program). CA issues commands that should persist until CA explicitly changes them. On Ecobee: Settings → Preferences → Hold Action → Until I change it.

Without these settings, CA's setpoints will appear to apply momentarily but then be overridden by the thermostat's own schedule, causing the thermostat display and HA's entity state to disagree.

3. Heating and cooling capability required — CA issues separate heat and cool commands (dual-setpoint heat_cool mode is not used for thermostat compatibility reasons). The HVAC system must support both heating and cooling. Heat-only or cool-only systems will not receive commands for the unsupported mode and are not a supported configuration.

All settings are editable after setup, plus advanced options:

• Learning enabled: Toggle the learning engine on/off
• Aggressive savings: More aggressive energy-saving strategies
• AI Investigator: Enable Claude-powered activity analysis; requires a Claude API key
• GitHub Integration: Configure a GitHub personal access token and repository for submitting investigation reports as GitHub issues directly from the dashboard
• Day-Type Thresholds: Customize the Hot/Warm/Mild/Cool temperature cutoffs (default 85/75/60/45°F); displayed in your configured unit

Accept or dismiss a learning suggestion.

service: climate_advisor.respond_to_suggestion
data:
  action: accept  # or "dismiss"
  suggestion_key: low_window_compliance

Force re-fetch of forecast data and reclassify the day. Useful for debugging.

service: climate_advisor.force_reclassify

Re-generate and resend the daily briefing notification.

service: climate_advisor.resend_briefing

Log a comprehensive diagnostic snapshot to HA logs at INFO level for troubleshooting.

service: climate_advisor.dump_diagnostics

Reset some or all learned data — useful after changing HVAC equipment or moving to a new location.

service: climate_advisor.reset_learning_data
data:
  scope: all  # or "thermal_model", "weather_bias", "suggestions"

Climate Advisor includes a built-in dashboard panel accessible from the HA sidebar. The panel provides:

• Current Status — Conditions card (day type, trend, outdoor temp), HVAC mode with inline indoor temp, setpoint, automation status, contact sensor states, separate WHF/HVAC fan status
• Daily Briefing — Full briefing with TLDR summary table, verbosity control (tldr_only/normal/verbose)
• Classification Details — Forecast data, window schedules, trend analysis
• Learning — Today's record, suggestions, compliance tracking
• Analysis (renamed from "AI") — Single report-type dropdown covering the deterministic Activity Record and the AI Investigator's deep analysis; both support Copy, Download .md, and Submit GitHub Issue
• Settings — Read-only view of all configuration grouped by category
• Debug — Automation state, force reclassify, resend briefing, diagnostics dump, prediction engine confidence levels

The dashboard is powered by 23 REST API endpoints under /api/climate_advisor/:

type: entities
title: Climate Advisor
entities:
  - entity: sensor.climate_advisor_day_type
    name: Today's Plan
  - entity: sensor.climate_advisor_trend
    name: Trend
  - entity: sensor.climate_advisor_next_action
    name: Your Next Action
  - entity: sensor.climate_advisor_next_automation
    name: Next Automation
  - entity: sensor.climate_advisor_comfort_score
    name: Comfort Score
  - entity: sensor.climate_advisor_contact_status
    name: Doors/Windows
  - entity: sensor.climate_advisor_fan_status
    name: Fan
  - entity: sensor.climate_advisor_occupancy
    name: Occupancy
  - entity: switch.climate_advisor_automation
    name: Automation Enabled
  - entity: sensor.climate_advisor_status
    name: System Status

See Issue #11 for full tracking.

• 5-level day type classification with trend analysis
• Daily briefing as primary UI (email/notification)
• Door/window pause automation with grace periods
• Occupancy-based setback with configurable delay
• Bedtime/morning scheduling with forecast-aware adjustments
• Runaway protection (runtime alerts, daily budgets)
• Learning engine foundation (90-day rolling window, 6 pattern detectors)
• Config flow wizard, HA sensor entities, dashboard API
• Flexible temperature source configuration
• Separate comfort/setback temps for heat and cool modes

• Persist operational state across restarts (#10)
• Populate DailyRecord fields (runtime, avg temp, comfort violations, window compliance)
• Per-sensor pause tracking and granular daily records (#12)
• Override direction/timing/magnitude analysis (#12)
• Built-in dashboard panel with status, briefing, classification, learning, settings, and debug tabs
• REST API endpoints powering the dashboard (now 22)
• Sensor entities + 1 automation switch (now 18 sensors)
• Observe-only mode (disable automation without uninstalling) (#19)
• Economizer two-phase cooling strategy (AC cool-down, ventilation maintain) (#27)
• Whole-house fan and HVAC fan mode support (#25)
• Occupancy awareness with home/away/vacation/guest modes
• Briefing TLDR summary table with verbosity control (#24)
• Contact sensor status surfaced in dashboard and as HA entity (#46)
• Resume from pause control with grace expiry re-check (#47)
• Cancel manual override from dashboard
• Reason logging on all thermostat adjustments (#16)
• Repairs flow for missing weather entity
• 4 HA services (respond to suggestion, force reclassify, resend briefing, dump diagnostics)
• 250-char notification limit for short notifications (#21)
• Startup race condition handling for weather entity (#36)

• Thermal model v2: two-parameter physics ODE (k_passive + k_active_heat/k_active_cool) replacing scalar rate model (#114)
• PendingThermalEvent state machine with post-heat decay curve OLS regression
• Pending thermal event persisted across HA restarts
• Optimized pre-heat/pre-cool timing and setback depth based on thermal performance
• Claude API client with circuit breaker, retry, rate limiting, and budget tracking (claude_api.py)
• AI skills framework — pluggable registry for AI analysis capabilities (ai_skills.py)
• AI Activity Report: timeline, HVAC decisions, anomalies, diagnostics (merged into the AI Investigator as one skill, Issue #563 — see ai_skills_investigator.py + ai_skills_context.py)
• Persistent 1-year chart log ring buffer for temperature/HVAC/fan/event data (chart_log.py)
• Sleep temperature setpoints (sleep_heat / sleep_cool) distinct from away setback
• Natural ventilation directional guard with hysteresis and reactivation lockout (#115)
• Dynamic Target Band: chart shows actual system targets (comfort/sleep/setback/vacation) (#119)
• Thermal model v3: six parallel observation types (hvac_heat, hvac_cool, passive_decay, fan_only_decay, ventilated_decay, solar_gain); extended ODE with k_vent and k_solar terms; k_passive collectable without HVAC cycles (#121)
• Dual-estimator framework for k_passive and k_vent_window (block-OLS + chart_log endpoint) (#146)
• Solar phase offset learning via chart_log daytime passive windows (#147)
• Chart historical navigation with before_ts anchor parameter (#160)
• Chart forward navigation into physics-simulated predicted future (#164)
• AI Investigation Analysis: unified view, report history, feedback buttons (#166)
• AI Investigator: deep cross-source analysis with KNOWN_FIXES registry, hypothesis generation (#177 noise reduction)
• GitHub issue submission from investigation panel with config flow GitHub Integration step (#180)
• Setpoint-only manual overrides enter manual grace period immediately (#170)
• DailyRecord accumulated counters survive HA restart (#176)
• Predicted indoor evening drop fixed: ODE mode uses classification for today (#172)

• Comfort band model — CA programs [comfort_heat / comfort_cool] and the thermostat holds it; HVAC is no longer micromanaged every 30 min (#249)
• Single-setpoint commands — every thermostat write is climate.set_temperature with mode + setpoint; heat_cool dual-setpoint mode dropped for compatibility (#301)
• Whole-house fan suppresses HVAC while active (#277)
• Override detection overhaul — clean-slate on restart, grace expiry notification, transient override detection (#282, #290)
• Ecobee deduplication bypass — double-write ensures commands reach the physical thermostat (#299)
• Pre-cool gate — ceiling reverts after target achieved, no overcooling (#295)
• k_solar confidence ladder (none / low / medium / high, graded by observation count) (#308)
• Solar phase offset daily re-fit from chart_log passive windows (#310)
• AC duty solar phase estimator — secondary EWMA for homes with summer-only AC (#312)
• Fan command suppression of false overrides; 30s post-fan setpoint verify (#313)
• Sleep setpoint ordering fix — sleep temps independent of daytime comfort bounds (#318)
• Pause state not persisted across restarts — clean-slate after HA restart (#263)
• Startup coalescing, stuck grace self-heal, nat-vent thermostatic cycling (#321)
• Nat-vent debounce step logging and next_automation surfacing (#320)
• Trend-aware overnight pre-cool banks cold thermal mass on warming-trend nights (#258)
• Automation Time card shows local HH:MM; Next User Action rename (#323, #326)
• Thread-safety fix — @callback on all async_call_later handlers (#325)
• Thermostatic fan fast loop — fan stops on temp change, not next 30-min cycle (#327)
• Deterministic Activity Report table; merged Vent bar (fan + nat-vent) in chart (#330, #331)
• Fan activity with trigger source visible in Activity Report (#332)
• Bedtime setback display fix — Next Automation and chart now show configured sleep temp, not trend-adjusted (#333)
• HA time-selector HH:MM:SS parse fix for sleep window — sleep setback no longer reverted every 30 min (#335)
• apply_classification enforces HVAC off whenever paused by an open door/window, hot or cold day (#337)
• Nat-vent + AC assist band re-arm and aggressive_savings gate against compressor use through open windows (#338)
• Occupancy away/vacation no longer arms setback while windows/doors are open — setback deferred until resume (#339)
• One thermostat write per sleep-band cycle instead of two conflicting setpoints; grace-started context visible in Activity Report (#341)
• Prediction Engines debug panel: stale "since" dates removed, k_solar/k_active_hvac confidence display fixed (#343, #345)
• Reconcile fan running (untracked) after thermostat starts it autonomously between AC cycles (#347)
• Analysis tab redesign — Activity Record (deterministic, non-AI) with indoor/outdoor temp columns; unified report-type dropdown (#352)
• Activity Record shows indoor/outdoor temp at thermostat decision events (#354)
• Fan ON/OFF state machine — nat-vent adoption, setpoint-echo suppression, post-grace reconciliation, WHF dual-entity support (#359, #360)
• WHF command-only mode (fan_state_feedback flag) to prevent false overrides from command-echo entities (#361)
• WHF ground-truth physical-state fallback and correct "running (manual override)" status (#363, #365)
• Status pane Conditions card (day type + trend + outdoor temp); HVAC card shows indoor temp inline (#367)
• Nat-vent bedtime continuation — fan runs to sleep target past bedtime, stops at sleep_cool; dual WHF/HVAC fan status rows (#370, #374)
• Day-type classification thresholds configurable in Settings, config entry migrated v15→v16 (#376)
• _build_predicted_indoor_future and chart data ODE computation offloaded to executor — eliminates event-loop blocking (#376)
• AI Investigator redesign — context registry of 11 independently-testable providers, focus-aware selection (~40% token reduction), 24h/30d GitHub issue cache, SSE streaming (#377)
• AI Investigator and Activity Report streaming UX — live text as chunks arrive instead of buffered-to-EOF (#380, #382)
• HACS compliance — dynamic README version badge, state file permissions hardened (0o600) (#384)
• HACS compliance fix — integration_type corrected from helper back to service, restoring visibility in Settings → Devices & Services (#388)
• Fan mode "Both" removed (per-device redesign judged too risky on the existing fan-reconcile logic); existing configs auto-migrate to whole-house fan (#424)
• Whole-house fan "stuck unconfirmed" self-heals within ~10 min instead of requiring a restart (#423)
• "Your Next Action" no longer advises a window/fan that would make things worse when outdoor is already unfavorable, in either direction (#428)
• Nat-vent's sleep-aware floor/ceiling made consistent across every check that reads it (proactive floor exit, reactivation gate, tick-level stop, dashboard status) — root cause of six related overnight flapping/status incidents (#400, #402, #415, #417, #427)
• Overnight pre-cool banking fixed — the AC-ceiling clamp anchored to the wrong (daytime) temperature range and could silently no-op; chart and real setpoint can no longer disagree on the pre-cool target (#436, #437)
• Default comfort/setback/sleep temperatures reformatted to match a real tuned household, including the initial setup wizard (previously stuck on stale pre-reformat defaults) (#438, #439)
• Pre-cool's AC trigger now reacts when natural ventilation ends ahead of its scheduled window, instead of waiting out a stale schedule (#440)
• Nat-vent decision surface (reactivation gate, fan-thermostat stop check, drift reconciliation, reactivation lockout, grace, retry/verify, pre-cool) extracted into independently unit-tested pure functions with differential and positive-control validation, closing the repeated-drift bug class behind #400/#402/#417/#427/#429 (#429)
• Duplicate "Comfort band applied" Activity Report entries at restart and grace-expiry eliminated with a short-window announcement dedup — the thermostat command itself was always correct, only the notification repeated (#444)
• Automated fan physical-drift self-corrections no longer mislabeled as a manual grace period in the Activity Report; repeated "fan running without CA warrant" reconcile attempts rate-limited to once per 5 minutes (#446)
• Dual-entity whole-house-fan setups (separate control + power-detection sensor) no longer silently drop reactivation commands — a plain command can be absorbed once the control entity's HA state already agrees with what's being commanded, so CA now forces a real transition when a real incident's device history proved the control entity was stuck "on" for hours (#449)
• AI Activity Report no longer misreports the whole-house fan as a contradiction during the brief window CA self-corrects a stale on/off flag; a matching gap in the dashboard's own internal state-consistency check fixed too (#458)
• Dashboard's setpoint-divergence indicator now accounts for away/vacation occupancy and uses the correct default sleep temperatures, instead of silently showing the wrong intended target overnight or while away (#462)
• AI Activity Report and Investigator's thermal-model sections no longer show an empty learning-health summary when the dashboard's Comfort Score sensor has real data for the same moment (#468)
• Chart's predicted-indoor curve can no longer silently disagree with its own displayed target band overnight when sleep temperatures aren't explicitly configured (#470)
• Continued consolidating the natural-ventilation decision surface (#429) into the rest of the codebase — a nat-vent floor formula, a fan-status suppression check, an occupancy-defer gate, and the dashboard's target-band resolver each converged from 2-4 independent copies down to one tested implementation, plus supporting test-infrastructure and coordinator-data cleanup (#452, #454, #456, #460, #464, #466)
• QuietCool RF wall-remote timer selections (1/2/4/8/12 hours) can now set the fan manual-override grace duration, so a physical remote timer press is honored instead of being overridden by CA's own automation partway through — optional, requires the gunkl/quietcool-house-fan firmware and a configured fan_remote_entity (#486)
• Outdoor temperature for weather-service-only installs (no dedicated sensor) is now interpolated between hourly forecast points and refreshed every 5 minutes instead of lagging/leading true conditions by up to an hour on a temperature ramp (#511)
• QuietCool remote speed changes (low/medium/high) are detected and shown on the dashboard as a comfort preference, without arming manual override/HVAC suppression the way a timer press does; a plain speed selection while the fan was off still counts as an override (#519)
• WHF status card now always trusts confirmed physical fan state over CA's internal session flags and refreshes on every real transition, fixing a stale "nat-vent active, fan idle" display that could persist for hours while the fan was genuinely running (#510)
• Warm/windows-day briefing text (header, body, AC-safety-net note, bedtime-setback note) now comes from one shared computation so the pieces can no longer contradict each other (#518)
• Dashboard WHF status card now shows the QuietCool remote's reported speed promptly after a remote press; Activity Report distinguishes remote-armed overrides from generic detected toggles (#524)
• Startup no longer arms the AC against an already-open window after an HA restart — startup now defers to the same door/window pause logic used the rest of the day (#523)
• Status, Next User Action, and Next Automation cards no longer restate the same "automation paused" narration in different words — each card sticks to its own job, and away/vacation mode gets rotating personality text in Next User Action (#527)
• Warm/mild-day window-close and reopen times fixed (a data-alignment bug could tell users to close windows hours too early); Next Automation card now predicts WHF/nat-vent start, warm-day window/AC events, and hot-day window-cooling opportunities using the same logic the automation itself uses (#528)
• Whole-house-fan-off grace period reliably sticks for its full protection window — a watchdog meant for a rare stuck-automation case was misfiring on ordinary fan-off almost every time; 8-hour RF remote timer sessions no longer produce a burst of contradictory decisions when the timer runs out (#530)
• Next Automation's "outdoor no longer helping" message now states when that's expected to happen instead of reading like a claim about right now; mild-day briefings use the same forecast-based window-close time warm days already got instead of a fixed 5:00 PM (#534)
• Whole-house fan can now soft-start for air movement and attic/thermal-mass purge as soon as outdoor reaches parity with indoor in the evening, once the day is confirmed past its peak — instead of waiting for outdoor to be measurably cooler; on by default, disable in settings for the old strict-delta behavior (#540)

• Seasonal performance baselines (after 1 year of data)
• Anomaly detection (e.g., "heating 30% higher than last November")
• Energy cost integration (utility rates → estimated cost)
• Savings tracking vs. "no automation" baseline

• Multi-zone HVAC support (multiple thermostats)
• Room-level occupancy detection
• Humidity-based decisions
• Energy source cost optimization
• Advanced thermal model with per-zone coefficients

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with a Home Assistant dev environment
5. Submit a pull request

custom_components/climate_advisor/
├── __init__.py          # Integration setup, service registration
├── manifest.json        # HA integration metadata
├── const.py             # Constants, thresholds, defaults
├── config_flow.py       # Setup wizard UI (7-step flow + options)
├── strings.json         # UI text for config flow
├── translations/
│   └── en.json          # English translations
├── coordinator.py       # Central brain — scheduling, events, data flow
├── classifier.py        # Day type and trend classification
├── briefing.py          # Daily briefing text generation
├── automation.py        # HVAC control logic (incl. economizer, fan)
├── learning.py          # Pattern tracking and suggestion engine
├── sensor.py            # 18 HA sensor entities for dashboards
├── switch.py            # Automation enable/disable switch
├── api.py               # 22 REST API endpoints for dashboard panel
├── state.py             # State persistence across restarts
├── repairs.py           # HA repairs flow for config issues
├── claude_api.py        # Claude API client: auth, retry, circuit breaker, rate limiting, budget tracking
├── ai_skills.py         # Lightweight skill registry framework for pluggable AI capabilities
├── ai_skills_investigator.py  # The sole registered AI skill ("investigator"): deep cross-source analysis on demand, plus silent/scheduled activity narration — merged from two separate skills, Issue #563
├── ai_skills_context.py # Context providers for AI skills — focus-aware, independently testable (16 providers, incl. the event-timeline renderers ported from the retired activity skill)
├── temperature.py       # Fahrenheit/Celsius conversion and formatting helpers
├── chart_log.py         # Persistent 1-year ring buffer of HVAC/fan/temperature data + event markers
├── nat_vent_gate.py     # Pure decision: nat-vent reactivation gate (direction/floor/ceiling)
├── fan_thermostat_decision.py  # Pure decision: tick-level fan stop check (free-cooling reversal, cooled-to-floor)
├── fan_drift_reconciliation.py # Pure decision: physical fan-state drift self-healing
├── nat_vent_reactivation_lockout.py  # Pure decision: post-exit reactivation lockout window
├── setpoint_verify_decision.py # Pure decision: post-fan-on/off setpoint verify outcome
├── desired_state.py     # Temporal-intention schema (grace, retry, revisit, notifications) + wired decisions
├── services.yaml        # Service definitions
├── frontend/
│   └── index.html       # Built-in dashboard panel
├── brand/               # Integration branding assets
├── icon.png             # Integration icon
└── [email protected]          # Retina integration icon

MIT