setup · diff
git:20260615.e3a990d to git:20260916.2ca1ddb
67 added, 25 removed. Audit B to B.
---
description: This skill should be used when the user asks to "install howl", "set up the statusline", "configure howl", "enable the HUD", or "install the statusline binary". It downloads the Howl binary and configures Claude Code to use it.
disable-model-invocation: true
---
# Howl Setup
Install and configure the Howl statusline HUD for Claude Code.
## What This Does
- 1. Download the latest Howl binary from GitHub Releases
- 2. Install it to `~/.claude/hud/howl`
- 3. Configure `~/.claude/settings.json` to use Howl as the statusline
- 4. Prompt the user to restart Claude Code
+ 1. Downloads the latest Howl binary from GitHub Releases, verifying its SHA256
+ 2. Installs it to `~/.claude/hud/howl`
+ 3. Points `statusLine` in `~/.claude/settings.json` at it
+ 4. Tells the user to restart Claude Code
+ Step 3 is why this skill exists. A plugin cannot set `statusLine` itself —
+ Claude Code allows only the `agent` and `subagentStatusLine` keys in a plugin's
+ own settings — so the main status line has to be written into the user's
+ settings by something running as the user. That is this script.
+
+ The agent panel needs no such step: the plugin ships `subagentStatusLine`
+ directly, so per-subagent rows start working as soon as the binary exists.
+
## Installation
Run the install script:
```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh"
```
- ## Verify Installation
+ It refuses to overwrite a `statusLine` that points at something other than
+ Howl. If the user already runs a different status line, report that and let
+ them decide rather than working around it.
- After the script completes, verify the binary works:
+ ## Verify Installation
```bash
+ ~/.claude/hud/howl --version
echo '{}' | ~/.claude/hud/howl
```
- The output should show a statusline with default values. If the binary is not found or fails, check:
+ The first prints the installed version. The second should print a status line
+ built from empty input — that exercises the whole render path, so if it prints
+ anything at all the binary works.
- - `~/.claude/hud/howl` exists and is executable
- - Run `chmod +x ~/.claude/hud/howl` if needed
+ If the binary is missing or not executable, check `~/.claude/hud/howl` and run
+ `chmod +x ~/.claude/hud/howl`.
## Post-Install
- Inform the user:
+ Tell the user:
- - Binary installed to `~/.claude/hud/howl`
- - Statusline configured in `~/.claude/settings.json`
- - **Restart Claude Code** to activate the statusline
+ - The binary is at `~/.claude/hud/howl`, and `statusLine` now points at it
+ - **Restart Claude Code** — the status line does not appear until then
+ - Display is configurable: `/howl:configure` for a preset, `/howl:customize`
+ for individual metrics, `/howl:threshold` for the colour thresholds
- ## Auto-Update
+ ## Staying Up To Date
- Once installed, the binary keeps itself current automatically:
+ Three separate things move, and they update differently. Explain whichever the
+ user asks about rather than reciting all three.
- - Claude Code auto-updates the **plugin** content (skills, scripts) from the marketplace.
- - The plugin's `SessionStart` hook (`scripts/sync-binary.sh`) then detects a plugin
- version change and re-downloads the matching **binary** in the background — so the
- binary never drifts from the plugin. It is a no-op (no network) when already in sync,
- and only updates an existing install (it never installs unprompted).
+ | What | How it updates |
+ | -------------------------------- | ---------------------------------------------------------------------- |
+ | Plugin content (skills, scripts) | Claude Code, from the marketplace — **only if auto-update is on** |
+ | The binary | This plugin's `SessionStart` hook, whenever the plugin version changes |
+ | Knowing an update exists | A badge on the status line, from a once-a-day check |
- To receive updates, ensure marketplace auto-update is enabled for the Howl marketplace
- (third-party marketplaces are not auto-updated by default):
+ **Auto-update is off by default for this marketplace.** Claude Code enables it
+ for its own marketplaces, not for third-party ones. Without it the plugin stays
+ on whatever version was current at install time, forever. Turn it on once:
+ ```
+ /plugin → Marketplaces → ai-screams-howl → Enable auto-update
+ ```
+
+ Once it is on, Claude Code refreshes after session start (with a delay of up to
+ ten minutes), and the hook then pulls the matching binary in the background.
+
+ To update right now instead of waiting:
+
```bash
- # Refresh the marketplace and update installed plugins
claude plugin marketplace update ai-screams-howl
+ claude plugin update howl@ai-screams-howl
```
- To force a binary update immediately, just re-run this setup (`/howl:setup`) or
- `bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh"`.
+ Or re-run this skill, which downloads the latest release directly.
+
+ ### The update badge
+
+ Claude Code has no "update available" indicator — its plugin list does not
+ carry the notion at all — so Howl shows its own. The `SessionStart` hook asks
+ GitHub for the latest release at most once a day, in the background, and writes
+ the answer to `~/.claude/hud/.update-available`. The status line reads that file
+ and shows `↑1.11.0` on the first line.
+
+ The check never runs from the status line itself: that command runs every few
+ seconds, and a network call there would wreck it.
+
+ To turn the badge off, set `hide_update_notice` in `~/.claude/hud/config.json`.
+ That also stops the daily check.
+
+ ```json
+ { "features": { "hide_update_notice": true } }
+ ```
## Troubleshooting
If the install fails:
- Check internet connectivity (needs access to github.com)
- Verify `curl` is available
- Try manual download from: https://github.com/ai-screams/howl/releases/latest
- Supported platforms: macOS (arm64/amd64), Linux (arm64/amd64)
If the statusline does not appear after restart:
- Check `~/.claude/settings.json` contains the `statusLine` field
- Verify the binary path is correct for this system
- Run `~/.claude/hud/howl --version` to confirm the binary works