@kentcdodds/venstar

@kentcdodds/venstar — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke / dryRun-style execute snippets, and edge cases. Do not disable live webhooks or jobs. There is no package secret — auth is the home connector MCP.

Secrets

None for this package. Requires the home MCP connector with Venstar thermostats configured (saved name and/or IP).

Import paths

Prefer static kody:@kentcdodds/venstar imports from execute. Do not lead with packages.invoke.

Default export returns a namespace with: listThermostats, summarizeClimate, getInfo, getSensors, getRuntimes, setComfort, setAutoRange, setAway, setSchedule. Named exports are also available from the same module.

Smoke test (read-only)

List thermostats / climate summary:

import venstarThermostats from 'kody:@kentcdodds/venstar'

export default async function main() {
	const venstar = await venstarThermostats()
	return await venstar.summarizeClimate()
	// => { ok: true, thermostats: ... }
}

Read one thermostat (no setpoint changes):

import venstarThermostats from 'kody:@kentcdodds/venstar'

export default async function main() {
	const venstar = await venstarThermostats()
	return await venstar.getInfo({ thermostat: 'apartment' })
	// => { ok: true, thermostat: 'apartment', info: { mode, heattemp, cooltemp, ... } }
}

Sensors / runtimes (also read-only):

import { getSensors, getRuntimes } from 'kody:@kentcdodds/venstar'

export default async function main() {
	return {
		sensors: await getSensors({ thermostat: 'apartment' }),
		runtimes: await getRuntimes({ thermostat: 'apartment' }),
	}
}

Mutations (explicit only)

There is no dryRun flag on Venstar control calls — they hit the live thermostat. Only call when the user explicitly requests a change.

import venstarThermostats from 'kody:@kentcdodds/venstar'

export default async function main() {
	const venstar = await venstarThermostats()
	// Only when the user asked to change setpoints
	return await venstar.setAutoRange({
		thermostat: 'apartment',
		heattemp: 68,
		cooltemp: 74,
	})
}

Away / schedule toggles require an explicit boolean:

import { setAway, setSchedule } from 'kody:@kentcdodds/venstar'

export default async function main() {
	return {
		away: await setAway({ thermostat: 'apartment', away: true }),
		schedule: await setSchedule({ thermostat: 'apartment', schedule: true }),
	}
}

Edge cases

• Fahrenheit setpoints must be finite numbers in 40–99.
• Auto mode: cooltemp must be greater than heattemp + minAutoGap (default gap 2).
• setComfort / setAutoRange / setAway / setSchedule return { ok: false, error } on validation or connector failures instead of always throwing.
• thermostat is the saved name or IP; omit only when the low-level connector has a default.
• Mode strings: off | heat | cool | auto. Fan: auto | on.