release: v3.6.0 — daemon-mode by default, fix --inline opt-out, py3.9 compat

`cs --setup` now writes `cs render` + refreshInterval=1 by default and
auto-starts the daemon, so the out-of-box experience is the daemon path
(~3-5ms/tick, <1% CPU) instead of inline (~30ms/tick, ~3% CPU at 1Hz).
Most users never opted into --fast manually; the inline default was
costing them CPU for no reason.

Bug fixed along the way: `cs --setup --inline` previously didn't downgrade
existing fast-mode users because ensure_statusline_configured used a
binary fast=True/False where False meant 'preserve existing'. Switched to
tri-state: None=preserve (auto-repair), True=force fast, False=force
inline. Daily auto-repair still preserves the user's choice; explicit
user requests are now respected.

Also folds in the py3.9 compat fixes (bf31092, b428037) and the CI/CoC/
hero/launch-kit work shipped in 650a575..4b86169 since 3.5.1.

Author: leeguooooo

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-statusbar",
-  "description": "Lightweight Claude Code status-line monitor with switchable styles, themes, and slash commands. v3.4 adds per-segment color management (each metric colors itself by its own severity), classic theme adoption, two new themes (catppuccin-mocha, tokyo-night), and per-severity color overrides via `cs config set color_ok|warn|hot`. v3.2 daemon fast-mode (`cs --setup --fast`) still ships for ~5× lower CPU at refreshInterval=1. Requires the `cs` CLI from PyPI (`pip install claude-statusbar` or `uv tool install claude-statusbar`).",
-  "version": "3.5.1",
+  "description": "Lightweight Claude Code status-line monitor with switchable styles, themes, and slash commands. v3.6.0 makes daemon (fast) mode the default for `cs --setup` — under 1% CPU continuously instead of ~3% inline at refreshInterval=1; pass `--inline` to opt back. v3.4 added per-segment color management, classic theme adoption, two new themes (catppuccin-mocha, tokyo-night), per-severity color overrides via `cs config set color_ok|warn|hot`. Requires the `cs` CLI from PyPI (`pip install claude-statusbar` or `uv tool install claude-statusbar`).",
+  "version": "3.6.0",
   "author": {
     "name": "leeguooooo",
     "email": "leeguooooo@gmail.com"

CHANGELOG.md

@@ -9,6 +9,41 @@ For a quick overview of the latest release, see the
 
 ---
 
+## v3.6.0 — 2026-05-08
+
+### Changed
+- **`cs --setup` defaults to daemon (fast) mode.** Previously you had to remember
+  `--fast` to get the long-lived daemon + `cs render` thin client; the bare
+  `cs --setup` wrote inline mode at refreshInterval=1, which costs ~3% CPU
+  continuously. Daemon mode keeps it under 1% with smoother per-second ticks.
+  Existing users running `cs --setup` after upgrading will be auto-bumped from
+  inline to daemon. To opt out, run `cs --setup --inline`. The legacy `--fast`
+  flag still works (no-op now). Daily auto-repair (background) preserves the
+  user's existing fast/inline choice — it doesn't reach into your settings to
+  change policy on you.
+
+### Fixed
+- **`cs --setup --inline` now actually downgrades.** In 3.5.x, passing `fast=False`
+  to `ensure_statusline_configured` quietly preserved an existing fast-mode
+  config (the OR-with-existing logic was meant for the auto-repair path but
+  blocked explicit user requests). The function is now tri-state:
+  `fast=None` preserves existing (auto-repair); `fast=True/False` is an
+  explicit user request and is respected.
+- **Python 3.9 compatibility.** `updater.py` and `cli.py` used PEP-604 union
+  syntax (`X | None`) at runtime, which 3.9 doesn't support. Added
+  `from __future__ import annotations` so all annotations are lazy strings.
+  CI on 3.9 was failing in 3.5.x — verified now passing on 3.9–3.12.
+
+### Added
+- GitHub Actions CI: pytest matrix on Python 3.9–3.12, ruff lint job,
+  cancel-in-progress concurrency, `contents: read` permissions only.
+- `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1).
+- Animated hero GIF at `docs/images/hero.gif` (driven by `scripts/hero.tape`,
+  rebuilt via `bash scripts/build-hero-gif.sh`).
+- Issue & PR templates under `.github/`.
+
+---
+
 ## v3.5.1 — 2026-05-08
 
 ### Changed

README.md

@@ -37,13 +37,15 @@ Lightweight Claude Code status-line monitor. Shows your 5h / 7d rate-limit usage
 
 ## Latest release
 
-**v3.5.1** (2026-05-08) — `npx skills add` install path, `show_cache_age` on by default.
+**v3.6.0** (2026-05-08) — **`cs --setup` now defaults to daemon (fast) mode**: under 1% CPU continuously instead of ~3% inline. Pass `--inline` to opt back. Also: py3.9 compat fixes, GitHub Actions CI, animated hero GIF.
+
+**v3.5.1** — `npx skills add` install path, `show_cache_age` on by default.
 
 **v3.5.0** — consolidated `claude-statusbar` skill: say *"switch theme to nord"* / *"余量颜色改成 #4ec85b"* and Claude Code routes it to the right `cs` command.
 
 **v3.4** — per-segment color management (each metric colors itself by its own severity), classic style finally respects themes, two new themes (`catppuccin-mocha`, `tokyo-night`), per-severity color overrides via `cs config set color_ok|warn|hot`.
 
-**v3.2** — daemon fast-mode for ~5× lower CPU at `refreshInterval=1`.
+**v3.2** — daemon fast-mode (now the default in v3.6.0) for ~5× lower CPU at `refreshInterval=1`.
 
 Full release notes in [CHANGELOG.md](CHANGELOG.md).
 
@@ -90,13 +92,13 @@ Then add to `~/.claude/settings.json`:
 {
   "statusLine": {
     "type": "command",
-    "command": "cs",
+    "command": "cs render",
     "refreshInterval": 1
   }
 }
 ```
 
-`cs --setup` writes `refreshInterval: 1` by default so the cache-age countdown ticks visibly. At 1Hz, the inline `cs` command runs ~30ms per render (~3% CPU continuously); if that's a concern, run `cs --setup --fast` instead — daemon mode brings it under 1%. To go quieter, set `refreshInterval` to a higher value (`30`, `60`) — `cs --setup` will preserve any explicit value you've already chosen.
+`cs --setup` (since v3.6.0) writes `cs render` + `refreshInterval: 1` by default — daemon mode, under 1% CPU continuously, smooth per-second ticks for the cache-age countdown. The daemon is auto-started by `cs --setup` and lazy-respawns on `cs render` if it ever dies, so you never see a frozen bar. To opt out and use the legacy inline path, run `cs --setup --inline` (writes plain `cs`, ~3% CPU at 1Hz). To go quieter regardless of mode, set `refreshInterval` to a higher value (`30`, `60`) — `cs --setup` preserves any explicit value you've already chosen.
 
 ### Skill-only install (already have `cs`)
 
@@ -215,21 +217,20 @@ Set via `cs config set <key> <value>`. Wipe everything back to defaults with `cs
 
 Override per-invocation via `--style` / `--theme` flags or `CLAUDE_STATUSBAR_STYLE` / `CLAUDE_STATUSBAR_THEME` env vars.
 
-## Fast mode — for `refreshInterval: 1`
+## Fast mode (daemon) — default since v3.6.0
 
-If you've set `"refreshInterval": 1` in `settings.json` (so the cache-age widget ticks every second), the default `cs` command runs ~45ms per render = ~4% CPU continuously. Fast mode brings that down to ~3-5ms per render = under 1% CPU by keeping a long-lived `cs daemon` that pre-renders into `~/.cache/claude-statusbar/rendered.ansi`. The statusLine command becomes `cs render` — a thin reader that just `cat`s the file.
+`cs --setup` writes `cs render` + `refreshInterval: 1` by default. A long-lived `cs daemon` pre-renders into `~/.cache/claude-statusbar/rendered.ansi`; the statusLine command (`cs render`) is a thin reader that just `cat`s the file. Each tick is ~3-5ms, so total CPU stays under 1% continuously. The legacy inline path (~30ms/tick, ~3% CPU at 1Hz) is still available via `cs --setup --inline`.
 
 ```bash
-cs --setup --fast        # writes settings.json + spins up the daemon
-cs daemon status         # check it's alive
+cs --setup               # default: daemon mode, auto-starts the daemon
+cs --setup --inline      # opt out, use legacy inline path
+cs daemon status         # check the daemon is alive
 cs daemon stop           # stop the daemon (statusLine falls back to inline)
 cs daemon start          # start it again
 ```
 
 Crash safety: if the daemon dies or freezes, `cs render` notices `rendered.meta.json` is older than 5s and falls back to inline render — and lazily re-spawns the daemon in the background. You never see a frozen status line.
 
-To revert: `cs --setup` (no `--fast`) restores the bare-`cs` legacy command.
-
 ### Optional: auto-start on login (launchd / systemd)
 
 Lazy-spawn (above) covers most cases — the daemon comes up on first `cs render`. If you want stronger guarantees (auto-start at login, OS restarts the daemon on crash, survives reboots without `cs render` needing to fire first):
@@ -297,8 +298,9 @@ cs preview                      # render every style × theme with YOUR real dat
 cs preview --theme nord         # filter to one theme
 cs preview --style hairline --theme dracula   # one specific combo
 
-# Daemon mode (v3.2+, opt-in)
-cs --setup --fast               # switch statusLine to `cs render` + start daemon
+# Daemon mode (default since v3.6.0; v3.2 introduced it as opt-in)
+cs --setup                      # default: writes `cs render` + starts daemon
+cs --setup --inline             # opt out, use legacy inline path
 cs daemon start                 # start daemon (manual)
 cs daemon stop                  # stop daemon
 cs daemon status                # pid + rendered.ansi freshness

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-statusbar"
-version = "3.5.1"
+version = "3.6.0"
 authors = [
     {name = "leeguooooo", email = "leeguooooo@gmail.com"}
 ]

src/claude_statusbar/cli.py

@@ -302,10 +302,14 @@ def main():
     parser.add_argument(
         "--fast",
         action="store_true",
+        help=argparse.SUPPRESS,  # daemon mode is the default since 3.6.0
+    )
+    parser.add_argument(
+        "--inline",
+        action="store_true",
         help=(
-            "When used with --setup, install the Phase B daemon mode: "
-            "statusLine command becomes `cs render` (3-5ms) backed by a "
-            "long-lived daemon. Use this when refreshInterval is 1 second."
+            "When used with --setup, opt out of daemon mode and use the "
+            "legacy inline path (no background daemon). Higher per-tick CPU."
         ),
     )
     parser.add_argument(
@@ -422,7 +426,10 @@ def env_float(name: str) -> float | None:
 
     if args.setup:
         from .setup import run_setup
-        return run_setup(verbose=True, fast=args.fast)
+        # Daemon (fast) mode is the default since 3.6.0; --inline opts out.
+        # Keep the legacy --fast flag accepted (no-op) so existing scripts work.
+        fast = not args.inline
+        return run_setup(verbose=True, fast=fast)
 
     if args.install_deps:
         print("Installing claude-monitor for full functionality...")

src/claude_statusbar/setup.py

@@ -15,7 +15,7 @@
 import shutil
 import sys
 from pathlib import Path
-from typing import Tuple
+from typing import Optional, Tuple
 
 from .cache import atomic_write_text
 
@@ -140,28 +140,34 @@ def _existing_uses_render(existing) -> bool:
     return len(parts) >= 2 and parts[1] == "render"
 
 
-def ensure_statusline_configured(fast: bool = False) -> Tuple[bool, str]:
+def ensure_statusline_configured(fast: Optional[bool] = None) -> Tuple[bool, str]:
     """Silently ensure settings.json has *our* statusLine config.
 
+    `fast` is tri-state:
+      - ``None``  (default): preserve the user's existing fast/inline choice;
+        for fresh writes (no statusLine yet), use daemon mode (the 3.6.0
+        default). This is what the daily auto-repair path passes — it
+        should never make a policy decision on the user's behalf.
+      - ``True``: force daemon mode (``cs render``). Used when the user runs
+        ``cs --setup`` (3.6.0 default) or the explicit ``cs --setup --fast``.
+      - ``False``: force inline mode. Used when the user runs
+        ``cs --setup --inline`` to opt out.
+
     Behavior:
-      - missing       → write our config (honors `fast` arg)
+      - missing       → write our config (fast=True if None, else honors arg)
       - foreign cmd   → leave alone (don't overwrite another tool's setup)
-      - our cmd, stale path → refresh, *preserving* the user's existing
-        fast/inline choice (so the daily auto-repair doesn't downgrade
-        a user who explicitly opted into `cs --setup --fast`).
-      - our cmd, current → no-op
-
-    `fast=True` only forces the write to `cs render`. `fast=False` does
-    NOT force a downgrade — it just means "if you have to write fresh,
-    pick the inline form". Existing fast-mode entries are left alone.
+      - our cmd       → refresh path; ``fast=None`` preserves existing,
+                        ``fast=True/False`` forces the write.
 
     Returns (changed, message).
     """
     settings = _read_settings()
     existing = settings.get("statusLine")
 
     if existing is None:
-        desired = _statusline_config(fast=fast)
+        # Fresh install: default to fast/daemon since 3.6.0.
+        write_fast = True if fast is None else fast
+        desired = _statusline_config(fast=write_fast)
         settings["statusLine"] = desired
         if _write_settings(settings):
             return True, f"Added statusLine config to {SETTINGS_PATH}"
@@ -177,11 +183,13 @@ def ensure_statusline_configured(fast: bool = False) -> Tuple[bool, str]:
             f"manually if you want claude-statusbar."
         )
 
-    # Ours already. Compute desired command preserving (a) fast mode if the
-    # user currently uses it (so the daily auto-repair never downgrades them)
-    # and (b) any explicit refreshInterval the user already set, so we don't
-    # silently bump someone's 60s cadence to our 1s default.
-    effective_fast = fast or _existing_uses_render(existing)
+    # Ours already. Determine effective_fast:
+    # - fast=None  → preserve user's existing choice
+    # - fast=bool  → respect it as an explicit user request
+    if fast is None:
+        effective_fast = _existing_uses_render(existing)
+    else:
+        effective_fast = fast
     existing_refresh = existing.get("refreshInterval")
     if isinstance(existing_refresh, (int, float)) and existing_refresh > 0:
         effective_refresh = int(existing_refresh)
@@ -287,12 +295,14 @@ def install_skills(force: bool = False) -> Tuple[int, list[str]]:
     return installed, skipped
 
 
-def run_setup(verbose: bool = True, install_cmds: bool = True, fast: bool = False) -> int:
+def run_setup(verbose: bool = True, install_cmds: bool = True, fast: bool = True) -> int:
     """Interactive setup: configure the statusLine and install slash commands.
 
-    `fast=True` opts into Phase B daemon mode (statusLine command becomes
-    ``cs render``). Also kicks off ``cs daemon start`` so the user sees
-    the speedup immediately.
+    `fast=True` (default since 3.6.0) installs Phase B daemon mode: statusLine
+    command becomes ``cs render``, backed by a long-lived daemon. Each tick is
+    ~3-5ms vs ~30ms inline, which keeps continuous CPU under 1% at
+    refreshInterval=1 (vs ~3% in inline mode). Pass ``fast=False`` to opt back
+    into the legacy inline path.
 
     Returns exit code (0 success, 1 partial failure, 2 unrecoverable).
     """

tests/test_daemon.py

@@ -486,7 +486,7 @@ def test_existing_uses_render_detects_fast_mode():
 
 
 def test_ensure_statusline_preserves_fast_mode(tmp_path: Path, monkeypatch):
-    """MUST-FIX from codex review: the daily auto-repair (default fast=False)
+    """MUST-FIX from codex review: the daily auto-repair (fast=None default)
     must NOT downgrade a user who already opted into `cs render`."""
     from claude_statusbar import setup as setup_mod
     settings = tmp_path / "settings.json"
@@ -496,8 +496,8 @@ def test_ensure_statusline_preserves_fast_mode(tmp_path: Path, monkeypatch):
         "statusLine": {"type": "command", "command": "/abs/path/cs render"},
     }), encoding="utf-8")
 
-    # Daily auto-repair tick — default fast=False.
-    changed, message = setup_mod.ensure_statusline_configured(fast=False)
+    # Daily auto-repair tick — fast=None (preserve), the new default in 3.6.0.
+    changed, message = setup_mod.ensure_statusline_configured()
 
     # Read what's there now.
     after = json.loads(settings.read_text(encoding="utf-8"))
@@ -508,6 +508,25 @@ def test_ensure_statusline_preserves_fast_mode(tmp_path: Path, monkeypatch):
     )
 
 
+def test_ensure_statusline_inline_explicit_downgrades(tmp_path: Path, monkeypatch):
+    """fast=False is now an EXPLICIT user request to switch to inline mode,
+    not a preserve-existing signal. Verify it actually downgrades."""
+    from claude_statusbar import setup as setup_mod
+    settings = tmp_path / "settings.json"
+    monkeypatch.setattr(setup_mod, "SETTINGS_PATH", settings)
+    settings.write_text(json.dumps({
+        "statusLine": {"type": "command", "command": "/abs/path/cs render"},
+    }), encoding="utf-8")
+
+    changed, _ = setup_mod.ensure_statusline_configured(fast=False)
+
+    after = json.loads(settings.read_text(encoding="utf-8"))
+    assert changed is True
+    assert not after["statusLine"]["command"].endswith(" render"), (
+        "explicit fast=False (cs --setup --inline) should downgrade to inline"
+    )
+
+
 def test_render_payload_signal_alarm_aborts_slow_render(monkeypatch):
     """Codex-flagged gap: the signal.alarm timeout in _render_payload was
     never exercised by tests. Mock core.main with time.sleep > timeout and

tests/test_setup.py

@@ -54,7 +54,11 @@ def test_creates_statusline_when_missing(isolated):
     assert "Added" in msg
     data = json.loads(settings.read_text(encoding="utf-8"))
     assert data["statusLine"]["type"] == "command"
-    assert Path(data["statusLine"]["command"]).name in setup_mod.OUR_COMMAND_NAMES
+    # Since 3.6.0 a fresh install defaults to daemon mode (`<cs> render`),
+    # so the command is split into the binary path + " render".
+    cmd_path = data["statusLine"]["command"].split()[0]
+    assert Path(cmd_path).name in setup_mod.OUR_COMMAND_NAMES
+    assert data["statusLine"]["command"].endswith(" render")
 
 
 def test_idempotent_when_already_configured(isolated):