Merge pull request #2829 from alexbelgium/claude_desktop/hourly-gains-and-headroom-backend

Claude Desktop: hourly rtk + headroom gains report + headroom proxy backend

README.md

@@ -56,7 +56,7 @@ If you want to do add the repository manually, please follow the procedure highl
 
 ### Number of addons
 
-- In the repository : 134
+- In the repository : 135
 - Installed : 508490
 
 ### Top 3
@@ -247,6 +247,14 @@ If you want to do add the repository manually, please follow the procedure highl
 ![amd64][amd64-badge]
 ![ingress][ingress-badge]
 
+✓ ![image](https://api.iconify.design/mdi/robot-happy.svg) [Claude Desktop](claude_desktop/) : Claude Desktop streamed through a browser with LinuxServer Selkies
+
+  ![Version](https://img.shields.io/badge/dynamic/yaml?label=Version&query=%24.version&url=https%3A%2F%2Fraw.githubusercontent.com%2Falexbelgium%2Fhassio-addons%2Fmaster%2Fclaude_desktop%2Fconfig.yaml)
+![Update](https://img.shields.io/badge/dynamic/json?label=Updated&query=%24.last_update&url=https%3A%2F%2Fraw.githubusercontent.com%2Falexbelgium%2Fhassio-addons%2Fmaster%2Fclaude_desktop%2Fupdater.json)
+![aarch64][aarch64-badge]
+![amd64][amd64-badge]
+![ingress][ingress-badge]
+
 ✓ ![image](https://api.iconify.design/mdi/movie-search.svg) [Cleanuparr](cleanuparr/) : Automatically removes stuck and unwanted downloads from your *arr and download clients
 
   ![Version](https://img.shields.io/badge/dynamic/yaml?label=Version&query=%24.version&url=https%3A%2F%2Fraw.githubusercontent.com%2Falexbelgium%2Fhassio-addons%2Fmaster%2Fcleanuparr%2Fconfig.yaml)

claude_desktop/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 1.7 (07-07-2026)
+
+- Add an hourly rtk + headroom token-savings report to the add-on log (`claude-gains-report.sh`, seeded via `/defaults/crontabs/root` and run by the base image's cron). Lets you confirm at a glance that both tools keep running and see accumulated gains — if the numbers stop growing, the tool has stopped working.
+- Run the Headroom optimization proxy as a supervised local backend (`svc-headroom` on 127.0.0.1:8787) so the `headroom_compress`/`headroom_retrieve` MCP tools can actually store/retrieve compressed content and record savings. It is a **backend only** — no client's `ANTHROPIC_BASE_URL` is routed through it, so the Claude Desktop app (which force-overrides it, [headroom #869](https://github.com/headroomlabs-ai/headroom/issues/869)) is unaffected. Previously the MCP server was registered but had no backend, so it recorded no savings.
+- Nudge Claude to use the headroom compression tools via a managed, idempotent block appended to the user's `CLAUDE.md` (removed automatically when `install_headroom` is disabled).
+
+## 1.6 (07-07-2026)
+
+- Fix default desktop launch failing when `install_headroom` is enabled (the default): the code rewrote the launch to `headroom wrap claude-desktop …`, but `headroom wrap` only supports coding-agent CLIs (`claude`, `codex`, ...) with arguments after `--`, so it produced an invalid command that left the app unlaunched. Leave the plain launch intact and instead register the `headroom` MCP server (`headroom mcp serve`) in Claude Desktop's config, exposing the `headroom_compress`/`headroom_retrieve`/`headroom_stats` tools inside the app. This is the supported headroom integration for Desktop, which overrides `ANTHROPIC_BASE_URL` so transparent proxy compression is not possible ([headroom #869](https://github.com/headroomlabs-ai/headroom/issues/869)). Disabling the option removes the entry again.
+- Make the autostart resilient: if the launch command fails to start, fall back to the plain Claude Desktop launch so the app always comes up.
+
 ## 1.5 (07-07-2026)
 
 - Change the default Claude Desktop data location to `/data/data`.

claude_desktop/Dockerfile

@@ -59,7 +59,6 @@ RUN curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://d
     apt-get install -y --no-install-recommends \
         claude-desktop \
         python3-pip \
-        gnome-keyring \
         libsecret-1-0 \
         dbus-x11 \
         git gh && \

claude_desktop/README.md

@@ -38,7 +38,7 @@ Claude Desktop sign-in requires a claude.ai plan that supports the Desktop app.
 | `DRINODE` | | Optional GPU device override for Selkies. |
 | `DNS_server` | `8.8.8.8` | DNS server used by the standard DNS module. |
 | `auto_update` | `true` | Check Anthropic's apt repository and upgrade `claude-desktop` at add-on startup. |
-| `install_headroom` | `true` | Make the baked-in `headroom` command available and log a usage hint. |
+| `install_headroom` | `true` | Register the baked-in `headroom` MCP server in Claude Desktop, exposing its `headroom_compress`/`headroom_retrieve`/`headroom_stats` context-compression tools inside the app. (Claude Desktop overrides `ANTHROPIC_BASE_URL`, so transparent proxy compression is not possible — MCP is the supported path; see [headroom #869](https://github.com/headroomlabs-ai/headroom/issues/869).) Disabling removes the entry again. |
 | `install_rtk` | `true` | Configure the rtk Claude Code `PreToolUse` hook in the persistent Claude Code settings. |
 | `install_caveman` | `true` | Install the caveman Claude Code plugin into the persistent Claude Code home. |
 | `install_github_cli` | `true` | Enable first-start checks and setup for the baked-in `git` and `gh` commands. |

claude_desktop/config.yaml

@@ -90,5 +90,5 @@ slug: claude_desktop
 tmpfs: true
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "1.5"
+version: "1.7"
 video: true

claude_desktop/rootfs/defaults/autostart

@@ -13,4 +13,19 @@ dbus-update-activation-environment --all >/dev/null 2>&1 || true
 
 # --password-store=gnome-libsecret forces Electron onto the libsecret backend instead of
 # falling back to plaintext (and warning that the sign-in will not be saved).
-claude-desktop --no-sandbox --disable-dev-shm-usage --password-store=gnome-libsecret
+CLAUDE_DESKTOP_COMMAND_FILE="/tmp/claude-desktop-command"
+DEFAULT_CLAUDE_DESKTOP_COMMAND="claude-desktop --no-sandbox --disable-dev-shm-usage --password-store=gnome-libsecret"
+if [ -s "$CLAUDE_DESKTOP_COMMAND_FILE" ]; then
+    CLAUDE_DESKTOP_COMMAND="$(cat "$CLAUDE_DESKTOP_COMMAND_FILE")"
+else
+    CLAUDE_DESKTOP_COMMAND="$DEFAULT_CLAUDE_DESKTOP_COMMAND"
+fi
+
+# Launch the configured command. If a custom/wrapped command fails to start, fall back to
+# the plain Claude Desktop launch so the desktop app still comes up for the user.
+if ! sh -c "$CLAUDE_DESKTOP_COMMAND"; then
+    if [ "$CLAUDE_DESKTOP_COMMAND" != "$DEFAULT_CLAUDE_DESKTOP_COMMAND" ]; then
+        echo "autostart: '$CLAUDE_DESKTOP_COMMAND' failed; falling back to default Claude Desktop launch" >&2
+        exec sh -c "$DEFAULT_CLAUDE_DESKTOP_COMMAND"
+    fi
+fi

claude_desktop/rootfs/defaults/crontabs/root

@@ -0,0 +1,4 @@
+# Hourly rtk + headroom token-savings report to the add-on log (heartbeat + gains).
+# Seeded to /data/data/crontabs/root by init-crontab-config and run by svc-cron; edit the
+# persistent copy to customize. Output goes to /proc/1/fd/1 so it shows in the add-on log.
+0 * * * * /usr/local/bin/claude-gains-report.sh > /proc/1/fd/1 2>&1

claude_desktop/rootfs/etc/cont-init.d/82-claude_tools.sh

@@ -4,21 +4,136 @@ set -e
 set -o pipefail
 mkdir -p "$HOME/.claude"
 
+CLAUDE_DESKTOP_COMMAND_FILE="/tmp/claude-desktop-command"
+DEFAULT_CLAUDE_DESKTOP_COMMAND='claude-desktop --no-sandbox --disable-dev-shm-usage --password-store=gnome-libsecret'
+printf '%s\n' "$DEFAULT_CLAUDE_DESKTOP_COMMAND" > "$CLAUDE_DESKTOP_COMMAND_FILE"
+
+# headroom's "wrap"/proxy routing works by setting ANTHROPIC_BASE_URL, which the Claude Desktop
+# Electron app force-overrides to the production endpoint (headroom #869), so transparent
+# compression cannot be applied to the desktop launch. The integration that does work with
+# Claude Desktop is headroom's MCP server, which exposes the headroom_compress/headroom_retrieve/
+# headroom_stats tools inside the app. Register it in Claude Desktop's MCP config, leaving the
+# plain launch untouched. The merge is idempotent and preserves any other MCP servers.
+CLAUDE_DESKTOP_CONFIG="$HOME/.config/Claude/claude_desktop_config.json"
 if bashio::config.true 'install_headroom'; then
     if command -v headroom &> /dev/null; then
-        bashio::log.info "headroom $(headroom --version 2> /dev/null || true) available. Use 'headroom wrap claude' or MCP mode from Claude Code."
+        bashio::log.info "headroom $(headroom --version 2> /dev/null || true) available; registering the headroom MCP server for Claude Desktop"
+        HEADROOM_BIN="$(command -v headroom)" CLAUDE_DESKTOP_CONFIG="$CLAUDE_DESKTOP_CONFIG" python3 - <<'PY' || bashio::log.warning "Unable to register the headroom MCP server automatically"
+import json
+import os
+from pathlib import Path
+
+path = Path(os.environ["CLAUDE_DESKTOP_CONFIG"])
+try:
+    data = json.loads(path.read_text()) if path.exists() else {}
+    if not isinstance(data, dict):
+        data = {}
+except Exception:
+    if path.exists():
+        path.rename(path.with_suffix(path.suffix + ".bak"))
+    data = {}
+servers = data.get("mcpServers")
+if not isinstance(servers, dict):
+    servers = {}
+    data["mcpServers"] = servers
+servers["headroom"] = {"command": os.environ.get("HEADROOM_BIN", "headroom"), "args": ["mcp", "serve"]}
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(data, indent=2) + "\n")
+PY
     else
         bashio::log.warning "headroom is not available"
     fi
+elif [ -f "$CLAUDE_DESKTOP_CONFIG" ]; then
+    bashio::log.info "Removing the headroom MCP server from Claude Desktop"
+    CLAUDE_DESKTOP_CONFIG="$CLAUDE_DESKTOP_CONFIG" python3 - <<'PY' || bashio::log.warning "Unable to remove the headroom MCP server automatically"
+import json
+import os
+from pathlib import Path
+
+path = Path(os.environ["CLAUDE_DESKTOP_CONFIG"])
+data = json.loads(path.read_text())
+if isinstance(data, dict):
+    servers = data.get("mcpServers")
+    if isinstance(servers, dict) and servers.pop("headroom", None) is not None:
+        if not servers:
+            data.pop("mcpServers", None)
+        path.write_text(json.dumps(data, indent=2) + "\n")
+PY
+fi
+
+# Guide Claude to actually use the headroom compression tools so the MCP integration produces
+# real savings (otherwise the tools sit unused and `headroom savings` stays empty). Managed,
+# idempotent block appended to the user's global CLAUDE.md; removed when headroom is disabled.
+CLAUDE_MD="$HOME/.claude/CLAUDE.md"
+HEADROOM_GUIDE_BEGIN="<!-- BEGIN headroom (managed by claude_desktop addon) -->"
+if bashio::config.true 'install_headroom'; then
+    mkdir -p "$(dirname "$CLAUDE_MD")"
+    if ! { [ -f "$CLAUDE_MD" ] && grep -qF "$HEADROOM_GUIDE_BEGIN" "$CLAUDE_MD"; }; then
+        bashio::log.info "Adding headroom usage guidance to CLAUDE.md"
+        {
+            [ -s "$CLAUDE_MD" ] && printf '\n'
+            cat <<'MD'
+<!-- BEGIN headroom (managed by claude_desktop addon) -->
+## Headroom context compression
+
+A local Headroom proxy (127.0.0.1:8787) backs the `headroom` MCP tools. To save context tokens:
+when you produce or read a **large, structured** blob you will keep referring to — file listings,
+search results, JSON/config dumps, big command outputs, roughly >500 tokens — call
+`mcp__headroom__headroom_compress` on it and keep the returned compressed text + `hash` instead of
+the raw content. Call `mcp__headroom__headroom_retrieve` with that hash when you need the full
+original back. Skip compression for error/stack-trace output (Headroom deliberately protects it)
+and for small or one-off content. Use `mcp__headroom__headroom_stats` to check savings.
+<!-- END headroom (managed by claude_desktop addon) -->
+MD
+        } >> "$CLAUDE_MD"
+    fi
+elif [ -f "$CLAUDE_MD" ] && grep -qF "$HEADROOM_GUIDE_BEGIN" "$CLAUDE_MD"; then
+    bashio::log.info "Removing headroom usage guidance from CLAUDE.md"
+    CLAUDE_MD="$CLAUDE_MD" python3 - <<'PY' || bashio::log.warning "Unable to remove headroom guidance automatically"
+import os
+import re
+from pathlib import Path
+
+path = Path(os.environ["CLAUDE_MD"])
+text = path.read_text()
+pattern = re.compile(
+    r"\n*<!-- BEGIN headroom \(managed by claude_desktop addon\) -->.*?"
+    r"<!-- END headroom \(managed by claude_desktop addon\) -->\n?",
+    re.DOTALL,
+)
+new = pattern.sub("", text)
+if new != text:
+    path.write_text(new)
+PY
 fi
 
 if bashio::config.true 'install_rtk'; then
     if command -v rtk &> /dev/null; then
-        if [ -f "$HOME/.claude/settings.json" ] && grep -q 'rtk' "$HOME/.claude/settings.json"; then
+        if [ -f "$HOME/.claude/settings.json" ] && grep -q 'rtk hook claude' "$HOME/.claude/settings.json"; then
             bashio::log.info "rtk Claude Code hook already configured"
         else
             bashio::log.info "Configuring rtk Claude Code hook"
-            rtk init -g || bashio::log.warning "rtk hook configuration failed"
+            RTK_NONINTERACTIVE=1 rtk init -g || bashio::log.warning "rtk global files configuration failed"
+            python3 - <<'PY' || bashio::log.warning "Unable to configure rtk hook automatically"
+import json
+from pathlib import Path
+path = Path.home() / ".claude" / "settings.json"
+try:
+    data = json.loads(path.read_text()) if path.exists() else {}
+    if not isinstance(data, dict):
+        data = {}
+except Exception:
+    if path.exists():
+        path.rename(path.with_suffix(path.suffix + ".bak"))
+    data = {}
+hooks = data.setdefault("hooks", {})
+pre = hooks.setdefault("PreToolUse", [])
+rtk_entry = {"matcher": "Bash", "hooks": [{"type": "command", "command": "rtk hook claude"}]}
+if not any("rtk hook claude" in json.dumps(entry) for entry in pre if isinstance(entry, dict)):
+    pre.append(rtk_entry)
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(data, indent=2) + "\n")
+PY
         fi
     else
         bashio::log.warning "rtk is not available"
@@ -49,7 +164,7 @@ if bashio::config.true 'install_caveman'; then
         bashio::log.info "caveman Claude Code plugin already configured"
     else
         bashio::log.info "Installing caveman Claude Code plugin"
-        curl --connect-timeout 10 --max-time 60 -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash || bashio::log.warning "caveman install failed (offline?)"
+        curl --connect-timeout 10 --max-time 60 -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash >/dev/null || bashio::log.warning "caveman install failed (offline?)"
     fi
 else
     bashio::log.info "Disabling caveman Claude Code plugin"

claude_desktop/rootfs/etc/cont-init.d/83-github_cli.sh

@@ -29,15 +29,13 @@ if bashio::config.has_value 'github_token'; then
     token="$(bashio::config 'github_token')"
     mkdir -p "$HOME/.config/gh"
     chmod 700 "$HOME/.config/gh"
-    export GH_TOKEN="$token"
-    export GITHUB_TOKEN="$token"
-    if gh auth status --hostname github.com > /dev/null 2>&1; then
+    if env -u GH_TOKEN -u GITHUB_TOKEN gh auth status --hostname github.com > /dev/null 2>&1; then
         bashio::log.info "GitHub CLI already authenticated for github.com"
     else
         bashio::log.info "Configuring GitHub CLI authentication for github.com"
-        printf '%s\n' "$token" | gh auth login --hostname github.com --with-token || bashio::log.warning "GitHub CLI authentication failed"
+        printf '%s\n' "$token" | env -u GH_TOKEN -u GITHUB_TOKEN gh auth login --hostname github.com --with-token || bashio::log.warning "GitHub CLI authentication failed"
     fi
-    gh auth setup-git --hostname github.com || bashio::log.warning "GitHub CLI git credential setup failed"
+    env -u GH_TOKEN -u GITHUB_TOKEN gh auth setup-git --hostname github.com || bashio::log.warning "GitHub CLI git credential setup failed"
 else
     bashio::log.info "GitHub CLI available. Set github_token to authenticate gh and git operations."
 fi

claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/run

@@ -0,0 +1,16 @@
+#!/usr/bin/with-contenv bashio
+# Headroom optimization proxy — runs ONLY as a local backend for the headroom MCP tools
+# (headroom_compress / headroom_retrieve, registered in 82-claude_tools.sh). It is NOT a
+# traffic router: no client's ANTHROPIC_BASE_URL is pointed at it, so the Claude Desktop
+# Electron app (which force-overrides ANTHROPIC_BASE_URL — headroom #869) and every other
+# client are unaffected. Without this backend the MCP tools cannot store/retrieve compressed
+# content and no savings are ever recorded.
+declare port=8787
+
+if bashio::config.true 'install_headroom' && command -v headroom >/dev/null 2>&1; then
+    bashio::log.info "svc-headroom: starting headroom proxy on 127.0.0.1:${port} (MCP backend only; no client routing)"
+    exec headroom proxy --host 127.0.0.1 --port "${port}"
+fi
+
+bashio::log.info "svc-headroom: install_headroom disabled or headroom not found; idling"
+exec sleep infinity

claude_desktop/rootfs/etc/s6-overlay/s6-rc.d/svc-headroom/type

@@ -0,0 +1 @@
+longrun

claude_desktop/rootfs/usr/local/bin/claude-gains-report.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/with-contenv bashio
+# Hourly rtk + headroom token-savings snapshot for the add-on log.
+# Invoked by cron (see /defaults/crontabs/root); its stdout is redirected to /proc/1/fd/1,
+# so the report appears in the add-on log. Doubles as a heartbeat: if the numbers stop
+# growing, the corresponding tool has stopped working.
+# with-contenv supplies HOME from the s6 envdir, so this honors a custom `data_location`
+# (see 20-folders.sh) instead of hardcoding /data/data; it also makes bashio::config
+# available for the install_headroom gate below.
+export NO_COLOR=1                                   # keep the add-on log free of ANSI color codes
+export PATH="/lsiopy/bin:/usr/local/bin:/usr/bin:/bin:${PATH}"
+
+have_rtk=false;      command -v rtk >/dev/null 2>&1      && have_rtk=true
+have_headroom=false; command -v headroom >/dev/null 2>&1 && have_headroom=true
+
+# headroom is pip-installed unconditionally at build time, so its binary is on PATH even
+# when install_headroom is off — gate on the same config svc-headroom checks, and only
+# fall back to have_headroom as a secondary availability guard.
+headroom_enabled=false
+if bashio::config.true 'install_headroom' && $have_headroom; then
+    headroom_enabled=true
+fi
+
+# Nothing to report if neither tool is active — stay quiet.
+if ! $have_rtk && ! $headroom_enabled; then exit 0; fi
+
+echo "===== claude gains report $(date '+%Y-%m-%d %H:%M:%S') ====="
+if $have_rtk; then
+    echo "--- rtk gain ---"
+    rtk gain 2>&1 || echo "[warn] rtk gain failed"
+fi
+if $headroom_enabled; then
+    echo "--- headroom savings ---"
+    headroom savings 2>&1 || echo "[warn] headroom savings failed"
+fi
+echo "===== end gains report ====="