Skip to main content

lg-thermal-watch: a night watch for your LG heat pump

CI Release 1.0.1 PyPI lg-thermal-watch Python 3.14 and 3.15 LG ThinQ Connect MCP server Claude Code plugin API behind a token mypy strict MIT licence Stars

A night watch, a temperature log and a dashboard for an LG heat pump, on LG's official ThinQ Connect API. When the room gets cold at night it switches the unit on, heats gently to your target with the fan on LOW, and switches it off again. In the meantime it logs the room every minute, counts every run, estimates the energy, and lets you, or your AI agent, ask how warm it is.

uv tool install lg-thermal-watch
lg-thermal-watch            # with your LG_THINQ_* credentials in the environment
lg-thermal-watch token      # the dashboard link

What it does

  • Night watch. Below a low threshold inside a night window (00:00 to 07:00 by default, in a timezone you set), it powers the unit on, heats to a high target with the fan LOW, then switches off. Settings survive restarts.
  • Temperature log. The room temperature every 60 seconds into SQLite, with min, max and mean over any window.
  • Runtime. Every on and off run with its duration and source, night watch or manual, and an estimated monthly energy chart.
  • Dashboard. The live temperature against the thresholds, what the watch is doing and why, a history chart with the nights and the heating runs marked, the settings, and manual heat and off.
  • Careful with the unit. Commands are bounded and rate limited, and the unit only gets the settings it lacks.

Built for the LG PC18SK indoor unit; any ThinQ Connect air conditioner that reports a room temperature should work.

How it works

LG ThinQ Connect API
        |
LGPC18SKAgent  <-  ThinQAgentController  <-  thinqconnect SDK
        |
        +--> LGPC18SKNightWatch   gentle heat when cold
        +--> RoomTempLogger       SQLite
        +--> RuntimeTracker       runs and energy
                |
          FastAPI /api, behind a token  -->  dashboard   -->  MCP server for agents

Install and run

You need an LG account with the unit in the ThinQ app, and a ThinQ Connect personal access token from LG's developer site. Put the credentials in an environment file with mode 600:

# ~/.config/lg-thermal-watch/lg-thermal-watch.env
LG_THINQ_ACCESS_TOKEN=...
LG_THINQ_CLIENT_ID=...
LG_THINQ_COUNTRY_CODE=PT
LG_THINQ_DEVICE_ID=...
LG_THERMAL_WATCH_TIMEZONE=Europe/Lisbon

Then run it as a systemd user service, so a reboot needs no manual step:

# ~/.config/systemd/user/lg-thermal-watch.service
[Unit]
Description=LG Thermal Watch

[Service]
EnvironmentFile=%h/.config/lg-thermal-watch/lg-thermal-watch.env
ExecStart=%h/.local/bin/lg-thermal-watch
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
systemctl --user enable --now lg-thermal-watch
lg-thermal-watch token      # open the link it prints, once per browser

User services stop when you log out unless lingering is on: loginctl enable-linger.

Secure by default

Every API call except the health check needs a token. The dashboard link stores it in an HttpOnly, SameSite=Strict cookie, so other sites in your browser can neither read it nor send requests that switch the unit, and requests that name a host your machine does not answer to are refused. It listens on 127.0.0.1 unless you say otherwise.

To reach it from your phone over Tailscale, listen on the Tailscale address only, which keeps the port off your local network: LG_THERMAL_WATCH_HOST=$(tailscale ip -4). Then open http://<tailscale-ip>:8000/?token=... once. Never expose the port to the internet.

With an AI agent

lg-thermal-watch is a Claude Code plugin: a skill with the rules, and an MCP server that talks to your running service with the same token. Ask "how cold did the living room get last night?" or "warm the room to 21".

/plugin install lg-thermal-watch --marketplace jpsanders/lg-thermal-watch

On Claude Code before 2.1.275: /plugin marketplace add jpsanders/lg-thermal-watch, then /plugin install lg-thermal-watch@lg-thermal-watch. Any MCP client can run the server directly:

{"mcpServers": {"lg-thermal-watch": {"command": "lg-thermal-watch", "args": ["mcp"]}}}

status, temperatures and runtime only read. heat, off and the three night watch tools act on a real heat pump, so they are marked destructive and your harness asks before calling them.

Configuration

Variable Meaning
LG_THINQ_ACCESS_TOKEN, LG_THINQ_CLIENT_ID, LG_THINQ_COUNTRY_CODE ThinQ Connect credentials. Required.
LG_THINQ_DEVICE_ID The unit's device id.
LG_THERMAL_WATCH_HOST, LG_THERMAL_WATCH_PORT Where to listen. Default 127.0.0.1:8000.
LG_THERMAL_WATCH_TOKEN The API token. Default: generated once into ~/.local/state/lg-thermal-watch/token.
LG_THERMAL_WATCH_TIMEZONE IANA zone of the night window, such as Europe/Lisbon.
LG_THERMAL_WATCH_DB SQLite file. Default ~/.local/share/lg-thermal-watch/room_temps.db.
LG_THERMAL_WATCH_NIGHTWATCH_CONFIG Night watch settings. Default ~/.config/lg-thermal-watch/nightwatch.json.
LG_THERMAL_WATCH_AVG_POWER_KW Assumed draw while running, for the energy estimate. Default 1.0.

The full list, the API and the night watch settings are in the manual: lg-thermal-watch guide, lg-thermal-watch man or docs/MANUAL.md. lg-thermal-watch man --install makes man lg-thermal-watch work.

Develop

make init-dev
make checks

make checks runs isort, black, editorconfig-checker, darglint, flake8, mypy in strict mode, bandit, the man page check and pytest with coverage. Tests use a mock unit and never talk to LG. CI runs them on Python 3.14 and 3.15 on Linux and macOS, then installs the wheel, starts the service and checks that a call without the token is refused. See CONTRIBUTING.md and AGENTS.md.

Star history

Star history of jpsanders/lg-thermal-watch

Licence

MIT. Made by James Phillip Sanders. LG and ThinQ are trademarks of LG Electronics; this project is not made or endorsed by LG.

Metadata

Release files for lg-thermal-watch 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lg-thermal-watch 1.0.1
File Size Uploaded Provenance Actions
lg_thermal_watch-1.0.1.tar.gz 258.3 kB With provenance Details for lg_thermal_watch-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lg-thermal-watch 1.0.1
File Interpreter ABI Platform Actions
lg_thermal_watch-1.0.1-py3-none-any.whl Python 3 none any Details for lg_thermal_watch-1.0.1-py3-none-any.whl

Total release size: 325.5 kB

Release files / lg_thermal_watch-1.0.1.tar.gz

Download URL lg_thermal_watch-1.0.1.tar.gz
Size 258.3 kB
Tags Source
SHA-256 checksum
How to use checksums
988353ce0921d2ec21986ae1e24fabfc59d4a6ba18075ae901f7d901aee6b5ac
BLAKE2b-256 checksum
How to use checksums
d30f864c59884d201ac3cf8524a6fd87f38820534e28b9344eeb95141a424a5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / lg_thermal_watch-1.0.1-py3-none-any.whl

Download URL lg_thermal_watch-1.0.1-py3-none-any.whl
Size 67.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5222f0a7baf57b52dfb6fdf3afc2f97418d583e0aa4b565ee116ebbbd4cf9800
BLAKE2b-256 checksum
How to use checksums
cb3dde0caf2769c75c7f5c4a11351ae69547a495705d9f76d8d662992fe446c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for lg-thermal-watch 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lg_thermal_watch-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page