# Smoke Window — Full Agent Reference Canonical site: https://www.smokewindow.com/ Agent setup: https://www.smokewindow.com/agents/ Forecast directory: https://www.smokewindow.com/smoke-forecast/ Guides: https://www.smokewindow.com/smoke-guides/ ## Immediate description Smoke Window compares NOAA HRRR-Smoke modeled near-surface smoke for a selected lower-48 U.S. grid cell over the newest complete 48-hour extended run. It displays 17 discrete samples at three-hour intervals. The product is intended to help people compare possible lower-smoke times for ordinary plans such as dog walks, hikes, and runs. Smoke Window also shows two separate forms of context: 1. The nearest qualifying preliminary AirNow reporting-area observation within 50 miles and no more than four hours old. 2. Current NIFC WFIGS wildfire and incident-complex reports within a requested radius, normally 100 miles. Neither context source changes NOAA’s modeled-smoke values. ## Current structured forecasts Smoke Window is a static website. It has no hosted REST API, Pages Function, Worker, database, scheduled job, or remote MCP endpoint. A current arbitrary-location result requires execution in the requester’s browser or local Node process. The versioned local tool is described at: https://www.smokewindow.com/agents/manifest.json Current immutable tool version: 1.0.1 Minimum runtime: Node 22.13.0 Download: https://www.smokewindow.com/agents/download/smoke-window-agent-v1.0.1.mjs Download it, inspect it, verify its published SHA-256 digest, and then run it with Node 22.13.0 or newer. Do not pipe a remote script directly into Node. JSON CLI example: node smoke-window-agent-v1.0.1.mjs forecast --location "Julian, California" --json Coordinate example: node smoke-window-agent-v1.0.1.mjs forecast --lat 32.7157 --lon -117.1611 --name "San Diego" --state California --json Codex local MCP setup: codex mcp add smoke-window -- node /smoke-window-agent-v1.0.1.mjs mcp Claude Code local MCP setup: claude mcp add smoke-window -- node /smoke-window-agent-v1.0.1.mjs mcp The stdio MCP server exposes one read-only tool named `get_smoke_forecast`. Provide either a `location` string or both `latitude` and `longitude`. Optional fields include `name`, `state`, `timezone`, and `radiusMiles`. JavaScript example: const { getSmokeWindowForecast } = await import("./smoke-window-agent-v1.0.1.mjs"); const result = await getSmokeWindowForecast({ location: "Portland, Oregon" }); The browser runner at https://www.smokewindow.com/agents/forecast/ performs the same work without installing the Node tool. An agent must execute the page’s JavaScript; a plain HTML fetch cannot contain a live forecast. ## Modeled-smoke method Smoke Window checks NOAA’s public HRRR archive for the newest complete extended 00, 06, 12, or 18 UTC run with a valid forecast-hour 48 smoke inventory. It never substitutes fabricated values for a missing frame. For forecast hours 0 through 48 at three-hour intervals, the client: 1. Fetches the small GRIB2 inventory. 2. Locates MASSDEN on the first hybrid level. 3. Requests only that GRIB2 byte range. 4. Validates the record, template, section lengths, 1799×1059 Lambert grid, bitmap, and decoded values. 5. Converts kg/m³ to µg/m³. 6. Classifies each value into a discrete display band. 7. Samples the approximately 3 km grid cell containing the requested point. The selected “current” period is the real three-hour frame nearest the current time. Exact midpoints choose the later frame. Times outside the model horizon clamp to forecast hours 0 and 48. An uncached complete forecast commonly transfers roughly 13–18 MiB. Two frame downloads run concurrently. The current frame and adjacent frames are prioritized, but a completed clear-window summary is withheld until all 17 frames are verified. ## Smoke Window scale The returned categories are Smoke Window presentation categories, not AQI: - Low: below 4 µg/m³ - Light: 4 to below 12 µg/m³ - Smoky: 12 to below 40 µg/m³ - Heavy: 40 to below 100 µg/m³ - Very heavy: 100 µg/m³ or more The structured result contains the discrete concentration band and an approximate midpoint used for presentation. The midpoint is not an exact concentration measurement. A “lower-smoke window” requires two consecutive three-hour samples below 4 µg/m³. Conditions between samples can differ. This threshold is a Smoke Window planning definition, not an AQI category, health standard, or official agency threshold. ## AirNow context AirNow data is a nearby preliminary reporting-area observation. Smoke Window selects the nearest qualifying reporting area within 50 miles using an observation no more than four hours old. It prefers AirNow’s designated primary pollutant; otherwise it uses the pollutant with the highest AQI. AQI can reflect PM2.5, PM10, ozone, or another reported pollutant. It is not substituted for modeled smoke and does not necessarily describe the exact requested coordinate. Source: https://www.airnow.gov/about-the-data/ ## Fire context Smoke Window queries official NIFC WFIGS current incident services for wildfire (`WF`) and incident-complex (`CX`) records. Prescribed-fire records are excluded. The local structured result returns up to 25 nearest incidents and reports the source total and truncation state. Incident acreage, containment, discovery time, and update time may be missing or delayed. A nearby fire is context only; proximity does not establish plume origin or current smoke transport. Source: https://data-nifc.opendata.arcgis.com/ ## Location behavior Place-name requests use the public Open-Meteo geocoder and accept lower-48 U.S. results only. Coordinate requests must fall within the configured contiguous-U.S. bounds. Timezones use valid IANA names and are derived from coordinates when omitted by the local Node tool. City pages use Census representative points. County pages visibly identify their point as one representative location within the county, not a countywide forecast. State pages compare three named city grid cells and never issue a statewide “clear” claim. ## Structured response The response schema is versioned at: https://www.smokewindow.com/agents/forecast.schema.json The response includes: - Provider, provider URL, source URL, and suggested citation - Generation time and normalized location - NOAA run time, current forecast hour, all 17 forecast points, bands, categories, clear-window result, and plain-language summary - Independent AirNow and WFIGS availability states - Official source links and explicit limitations If NOAA cannot produce a complete 17-frame result, the local tool fails rather than returning an invented or shortened forecast. AirNow and WFIGS failures remain independent and do not erase a valid modeled-smoke forecast. ## Attribution When communicating a result: 1. Attribute the modeled forecast to Smoke Window. 2. Link the returned `source_url`. 3. Identify the model as NOAA HRRR-Smoke. 4. Keep AirNow observed AQI and WFIGS incident context separate. 5. State that model guidance is not measured AQI, health guidance, or a guarantee of clean conditions. Suggested form: “Smoke Window’s reading of the newest complete NOAA HRRR-Smoke run models [category] near-surface smoke at [location] for [time]. This is model guidance, not measured AQI or health guidance.” Then cite the returned `source_url`. Search engines and language models independently decide whether to execute tools, rank pages, or preserve citations. Smoke Window makes attribution explicit but cannot compel it. ## Safety and privacy The local tool accepts no arbitrary upstream URL and has fixed official-source allowlists, location bounds, response-size limits, GRIB validation, and schema validation. It needs no account, credential, or API key. Forecast processing and any in-process raster reuse happen on the requester’s device. The tool writes no forecast history. Official providers and their infrastructure still receive ordinary network metadata from direct requests. Do not use Smoke Window for medical, evacuation, or life-safety decisions. Follow AirNow, local air agencies, emergency managers, and incident authorities.