# History

> Use when reading Home Assistant entity history, logbook timelines, or long-term statistics through HA NOVA Relay.

- **Type:** Skill
- **Install:** `agentstack add skill-markusleben-ha-nova-history`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [markusleben](https://agentstack.voostack.com/s/markusleben)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [markusleben](https://github.com/markusleben)
- **Source:** https://github.com/markusleben/ha-nova/tree/main/skills/history
- **Website:** https://github.com/markusleben/ha-nova

## Install

```sh
agentstack add skill-markusleben-ha-nova-history
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HA NOVA History

## Scope

Read-only timeline work:
- entity state history over a bounded time range
- logbook queries over a bounded time range
- long-term statistics over a bounded time range
- concise "what happened?" summaries

Not in scope:
- live subscriptions
- system logs
- trace debugging
- calendar queries
- giant raw exports

Use `ha-nova:read` for traces and `ha-nova:fallback` for calendars or subscriptions.

## Bootstrap (once per session)

Verify relay CLI: `ha-nova relay health`
If this fails: `ha-nova setup`

## Relay Contract

Use file-based relay requests:
- `ha-nova relay core --method GET --path  --out `
- `ha-nova relay core --method GET --path  --out `
- `ha-nova relay ws --data-file  --out `
- `ha-nova relay jq --file  --jq-file `

For `ha-nova relay jq`, the filter is positional unless `--jq-file` is used. Do not invent a `--jq` flag.

Canonical paths:
- `/api/history/period/?filter_entity_id=&end_time=`
- `/api/logbook/?entity=&end_time=`
- `recorder/statistics_during_period`

Prefer `minimal_response` and `no_attributes` on large history queries when the task only needs state transitions.
Relay-core response shape here stays under `.data.body`.
- history series: `.data.body[0]`
- logbook entries: `.data.body`
- do not probe `.[0]` or `.[0][0]` against the relay envelope
Recorder statistics response stays under WS `.data`.

## Flow

1. Resolve the exact entity target when needed.
2. Set a bounded window.
   - if the user gave a range, use it
   - otherwise default to the last 24 hours for history/logbook
   - otherwise default to the last 30 days for statistics/trend questions
   - if the requested window is too broad, narrow it before querying
3. Choose the source:
   - history for state transitions and values
   - logbook for human-readable events and automation activity
   - statistics for multi-day trends, comparisons, or long-term summaries
4. Execute the read into ``.
5. Summarize first:
   - key transitions
   - first/last seen values
   - notable gaps or bursts
   - key periods or trend direction for statistics
   - if the raw state series can contain `unknown` or `unavailable`, do not run numeric min/max across the whole series unless you first filter to numeric states safely
   - prefer simple reductions that do not depend on fragile timestamp parsing unless the user explicitly asked for gap analysis
   - for the default summary, do not build complex jq expressions just to recover min/max event timestamps; numeric range plus a few direct sample timestamps is enough
6. Only show raw excerpts if the user explicitly asks.

## Output Format

- `Target`
- `Window`
- `Summary`
- `Key events`, `Key transitions`, or `Key periods`
- `Next step`

Keep default output compact. Raw payload dumps are opt-in only.

## Safety

- Read-only skill. No writes.
- No guessed entity ids.
- If more than one entity could match, ask one blocking question.
- If the data is incomplete for the requested conclusion, say so explicitly.

## Guardrails

- Never run an unbounded history/logbook/statistics query.
- Cap default investigative windows at 24 hours unless the user asked for more.
- If the user asks for a very large export, narrow the request first.
- Prefer a short summary over dumping a long raw timeline.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [markusleben](https://github.com/markusleben)
- **Source:** [markusleben/ha-nova](https://github.com/markusleben/ha-nova)
- **License:** MIT
- **Homepage:** https://github.com/markusleben/ha-nova

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-markusleben-ha-nova-history
- Seller: https://agentstack.voostack.com/s/markusleben
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.