Claude Indicators
=================

A small always-on-top widget with a traffic light for every Claude Code session on your PC
(desktop app Code tab and terminal sessions):

  Red, blinking     the session needs you (permission prompt, a question, a plan to approve)
  Amber, pulsing    working
  Green             finished, your turn (blinks until you open it)
  Faded             no activity for 15 minutes: interrupted or closed

Each light shows the session's name, its folder and how full its context window is. Lights can be
grouped by project, shown as compact dots, and the widget can show your plan usage (session and
weekly limits).


Requirements
------------
- Windows 10 or 11, 64-bit
- .NET 8 Desktop Runtime (x64): https://dotnet.microsoft.com/download/dotnet/8.0
  (the installer checks and tells you if it's missing)
- Claude Code (desktop app or CLI)


Install
-------
1. Extract the zip to any folder.
2. In that folder, run in a terminal:

       powershell -ExecutionPolicy Bypass -File .\install.ps1 -Startup

   Leave out -Startup if you don't want it to start when you sign in.

The installer:
- copies the widget to %LOCALAPPDATA%\ClaudeIndicators
- adds one hook to your ~/.claude/settings.json for these events: SessionStart, UserPromptSubmit,
  PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Notification, Stop, SessionEnd.
  Your existing settings and hooks are kept, and a backup of the file is saved next to it first.
- sets the same program as your Claude Code status line, only if you don't have one already. Claude
  reports plan usage (session and weekly limits) only to the status line; it prints nothing, so your
  status bar stays empty. If you already have a status line it is kept and plan usage isn't shown.
- starts the widget

Sessions that were already open start reporting on their next prompt.

To upgrade, run install.ps1 from the newer zip. Your settings and window position are kept.


Using it
--------
- Drag the widget anywhere; it remembers where you put it.
- Double-click a light to open that session in the Claude desktop app (sessions running in a terminal
  can't be opened this way).
- Right-click a light: open, open folder, copy session id, dismiss.
- Right-click the background: dismiss all finished, vertical layout, compact (dots), group by project,
  show plan usage, show context usage, always on top, Jira cards, Compass workers, exit.
  The version is at the bottom of this menu.
- Plan usage shows the numbers from the last reply in a session that runs the status line ("as of"
  time), so it isn't live while every session is idle. Per-model weekly limits aren't available.
- Jira cards are optional: right-click > Jira settings. Your API token is stored encrypted for your
  Windows user only.


Privacy
-------
The widget only reads local files that Claude Code already writes (~/.claude). Nothing is sent anywhere,
except calls to Jira with your own account if you connect it.


Uninstall
---------
    powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

This removes the hook from ~/.claude/settings.json (backup saved first), the Startup shortcut and the
program files. Add -RemoveSettings to also delete the widget's own settings.


Troubleshooting
---------------
- Windows warns about the program: it isn't code-signed. The installer unblocks the files from the zip;
  if SmartScreen still asks, choose "More info" > "Run anyway".
- A session's light never changes: restart that session so it loads the hook.
- To see why the hook does nothing, set the environment variable CLAUDE_INDICATORS_DEBUG=1 and it writes
  errors to stderr.
