# AppDaemon for Home Assistant — VS Code extension

Version: **0.2.0**

## Install or update

Open **Extensions**, select **… → Install from VSIX…**, and choose
`vscode-appdaemon-0.2.0.vsix`. Reload VS Code when prompted.

## Log explorer

Select **$(list-tree) AD Logs** in the VS Code status bar, or run **AppDaemon: Explore Logs** from the Command Palette. The explorer opens in a central editor tab, including when no document is open.

By default, it reads the existing AppDaemon text logs from the workspace:

- `logs/appdaemon.log`
- `logs/error.log`
- `logs/virtualsensors.log`

The explorer groups lines by the app name in the standard AppDaemon log format. It provides INFO/WARNING/ERROR counts, expandable app histories, links to app definitions, relative timestamps, sorting by latest activity or app name, text/time/level filters, live updates, and raw-log navigation. Duplicate error lines found in multiple files are merged. The log reader handles file rotation, truncation, multiline exceptions, UTF-8, and legacy Windows-1252 bytes.

**AD Logs** turns red when the loaded logs contain an ERROR or CRITICAL entry. **Clear logs** empties the configured log files and clears the current explorer history.

Lines carrying the same `[group=<name>:<id>]` marker are grouped together, and the supplied name is shown in the explorer. Ordinary AppDaemon lines without a group marker remain individual log entries. Trace metadata can still be used for causal links where present.

## Settings

```json
{
  "appdaemon.haUrl": "http://homeassistant:8123",
  "appdaemon.haToken": "<HOME_ASSISTANT_TOKEN>",
  "appdaemon.adUrl": "http://localhost:5050",
  "appdaemon.errorLogPath": "logs/error.log",
  "appdaemon.mainLogPath": "logs/appdaemon.log",
  "appdaemon.entityRefreshInterval": 300,
  "appdaemon.logExplorerPaths": [
    "logs/appdaemon.log",
    "logs/error.log",
    "logs/virtualsensors.log"
  ],
  "appdaemon.logTimezone": "Europe/Berlin",
  "appdaemon.logEncoding": "auto"
}
```

| Setting | Purpose |
| --- | --- |
| `haUrl`, `haToken` | Home Assistant connection for entity information |
| `adUrl` | AppDaemon HTTP API URL |
| `errorLogPath`, `mainLogPath` | Log locations relative to the workspace |
| `entityRefreshInterval` | Entity refresh interval in seconds |
| `logExplorerPaths` | Text log files followed by the explorer |
| `logTimezone` | Timezone used to interpret AppDaemon timestamps |
| `logEncoding` | `auto`, `utf8`, or `windows-1252` for text logs |

Do not commit your Home Assistant token. Use user settings or an ignored local
settings file.

## Other extension features

- Home Assistant entity completion and hover information in Python/YAML.
- Navigation to AppDaemon app and virtual-sensor definitions.
- AppDaemon errors as VS Code diagnostics and an output channel.
- Status bar actions for app reload, Home Assistant restart, log exploration,
  and apps defined in the active YAML file.

| Shortcut | Action |
| --- | --- |
| Ctrl+Shift+A / Cmd+Shift+A | Go to App |
| Ctrl+Shift+V / Cmd+Shift+V | Go to Virtual Sensor |

Commands are available under **AppDaemon:** in the Command Palette: **Go to
App**, **Restart Apps in Current File**, **Reload Apps**, **Restart Home
Assistant**, **Toggle Production Mode**, **Show Error Log**, **Refresh Entity
List**, **Clear Error Diagnostics**, and **Explore Logs**.

## Verification

```sh
npm test
```

The log explorer preview is available at `docs/log-explorer-preview.html` in the
workspace; it uses sample data and is not a live log server.