/pulse

description: Configure the usage-pulse status bar (setup, themes, widgets, providers, hooks)
argument-hint: "[setup | <theme> | show | providers | hooks | update | help]"

Configure your Claude status bars — setup, themes, widgets, providers, hooks and more. $ARGUMENTS

---

1. Find the script (once, before anything else)

1. Read `settings.json` in Claude Code's config dir (`$CLAUDE_CONFIG_DIR` if it is set, otherwise `~/.claude`). If `statusLine.command` contains `claude_status.py`, take the script path from it: strip the quotes and expand `$HOME`. Keep the interpreter at the start of that same command as PY (for example `C:/Users/me/AppData/Local/Programs/Python/Python313/python.exe` or `python3`). 2. Otherwise use the Glob tool for `**/claude_status.py` under `~/.claude/plugins/` and pick the result whose path contains `usage-pulse` (or `claude-pulse`, the name before 3.5.0). 3. Otherwise try `~/.usage-pulse/claude_status.py`, then `~/.claude-pulse/claude_status.py` (an install from before the rename). 4. If nothing is found, say: "usage-pulse isn't installed yet. Run `/usage-pulse:setup` (plugin) or the installer from the README, then `/pulse setup`." and stop.

Save the path as SCRIPT_PATH. If no PY was found, use `python` (Windows) or `python3` (macOS/Linux). Every command below is `PY "SCRIPT_PATH" <flag>`.

2. Rules

• After any change, say it shows on the status line's next refresh.
• Never paste raw `--config` output (it is ANSI). Summarise it in words.
• Ask with AskUserQuestion: one question per step, at most 4 options, "Other…" last when free text makes sense.
• The live theme picker and the full-screen wizard need a real terminal, which you don't have. When the user wants them, give them the line to type themselves, prefixed with `!`:

`!PY "SCRIPT_PATH" --pick-theme` or `!PY "SCRIPT_PATH" --setup` If they see a static list instead, their terminal isn't interactive; carry on with the questions here.

• Hook or status-line changes need a Claude Code restart; say so when you make one.
• `PY "SCRIPT_PATH" --help` lists every flag. Use it when a request doesn't match the table below.

3. Routing — what to do with $ARGUMENTS

| $ARGUMENTS | Do this | |---|---| | empty, `menu`, `themes`, `theme` | Top menu (section 4) | | `setup`, `wizard`, `install`, `start` | Setup path (section 5) | | a theme name: `default` `ocean` `sunset` `mono` `neon` `pride` `frost` `ember` `candy` `rainbow` | `--theme <name>` | | `pick`, `picker`, `pick-theme` | Give the user `!PY "SCRIPT_PATH" --pick-theme` to type. Controls: ↑/↓ or j/k move, Enter keep, Esc cancel | | `show`, `show all`, `preview`, `colors`, `colours` | Run `--show-themes` and `--show-colors` (two Bash calls in parallel), show the output, then say only: "Press **Ctrl+O** to expand and see the colours." | | `show <parts>` / `hide <parts>` | `--show <parts>` / `--hide <parts>` (comma-separated, see the list below) | | `animate <off/rainbow/pulse/glow/shift/on>` | `--animate <mode>` | | `speed <slow/normal/fast>`, `animation-speed …` | `--animation-speed <speed>` | | `text-color <name>`, `text-colour <name>` | `--text-color <name>` | | `bar-size <size>`, `size <size>` | `--bar-size <size>` (small, small-medium, medium, medium-large, large, or auto to shrink to fit) | | `bar-style <name>`, `style <name>` | `--bar-style <name>` | | `layout <name>` | `--layout <standard/compact/minimal/percent-first>` | | `wrap <off/auto>`, `max-width <20-100>` | `--wrap …`, `--max-width …` | | `currency <symbol>` | `--currency <symbol>` (costs are converted from USD at a daily rate; an ISO code such as DKK works too) | | `clock <12h/24h>` | `--clock-format <12h/24h>` | | `effort-format <labeled/full/short>` | `--effort-format <value>` | | `weekly-timer <auto/countdown/date/full>` | `--weekly-timer-format <value>` | | `context-format <percent/tokens>` | `--context-format <value>` | | `extra-display <auto/full/amount>` | `--extra-display <value>` | | `streak-style <fire/text>` | `--streak-style <value>` | | `pace-style <arrows/percent>` | `--pace-style <value>` | | `caps`, `models`, `model caps` | Caps question (5.4), then `--show`/`--hide opus,sonnet,fable` | | `providers`, `accounts`, `detect` | Providers path (section 6) | | `copilot`, `copilot install` | `--install-copilot`: makes this bar GitHub Copilot CLI's status line too (writes only Copilot's `settings.json`, keeps a backup). Say Copilot CLI needs a restart. For a Copilot row under the Claude bar instead, use the Providers path | | `copilot remove`, `copilot uninstall` | `--uninstall-copilot` | | `providers label <id> <text>` | `--providers label <id> "<text>"` | | `providers enable <ids>` / `disable <ids>` | `--providers enable <ids>` / `--providers disable <ids>` | | `hooks` | Hooks question (5.2) | | `hooks heartbeat`, `hooks agents`, `hooks team`, `hooks all` | `--install-hooks --only <group>` (`all` = `--install-hooks`) | | `focus start [min]`, `focus stop`, `focus status` | `--focus <action> [minutes]` (default 25 minutes) | | `budget <amount/off>` | `--budget <value>`. It mirrors Claude Code's `--max-budget-usd`, which can't be read automatically | | `limits`, `limits k=v,…` | `--limits <value>` (keys: subagent_spawns, subagent_concurrent, web_searches) | | `preset <name>`, `minimal` | `--preset <name>` (`default` is a full factory reset: confirm first) | | `priority <widget=N,…>` | `--priority <value>` | | `update` | `--update`, show the output | | `stats`, `heatmap` | `--stats` / `--heatmap`, show the output | | `config`, `settings` | `--config`, then summarise | | `help` | `--help`, show the output |

Valid parts: session, weekly, context, timer, weekly_timer, session_bar, weekly_bar, context_bar, cost, model, branch, heartbeat, update, claude_update, opus, sonnet, fable, plan, extra, effort, fast_mode, thinking, agent, worktree, pomodoro, context_warning, staleness, lines, cumulative_cost, weekly_cost, cache, cache_warm, spend_limit, repo, session_name, providers, subag