GSD Monitor

A lightweight monitoring system for GSD (Get Shit Done) and Claude Code sessions.

Problem: GSD/Claude Code runs autonomously for extended periods, then suddenly needs user input. Without monitoring, you waste time either watching constantly or missing input prompts.

Solution: Hook scripts track session state, and a web dashboard alerts you with sound and browser notifications when Claude needs your attention.

Features

• Web-based dashboard accessible from any device on your network
• Two-step notifications - yellow warning when idle, red alert when input needed
• Browser notifications and audio alerts (two-tone doorbell sound)
• GSD project integration - shows current phase and plan progress
• Mobile support - responsive design with QR code for phone access
• Auto-follow sessions - tracks sessions across /clear operations
• Non-invasive - appends to existing hooks, doesn't replace
• Update-safe - marked hooks can be cleanly removed/updated
• Automatic backups before modifying settings
• Works with Claude Code without GSD Shows less information but works with just Claude Code too
• Now works with Claude Code plugins too (v 1.2) Detects if the Claude Code session is coming from a VSCodium/VSCode/JetBrains session & handles 60 seconds alerts for these too
• Claude's Last Message display (v 1.3) See Claude's actual question or prompt in the monitor UI - no need to switch to the terminal

Installation

# Clone or download this directory
cd gsd-monitor

# Install hooks (global)
python injector.py inject

# Or install to current project only
python injector.py inject --local

# Explicitly install to global settings only
python injector.py inject --global

# Install web monitor dependencies
cd gsd-monitor-web
pip install -r requirements.txt

Upgrading from Previous Versions

Users on v1.1 or earlier must reinstall hooks when upgrading - the hook files have changed in v1.2 and v1.3. See the CHANGELOG for details on what's new in each version.

cd gsd-monitor

# Remove old hooks
python injector.py remove

# Install updated hooks
python injector.py inject

What's New

v1.3 - Claude's Last Message display, NOTIFICATION status alerts, markdown rendering

v1.2 - Plugin alert support (VSCode/VSCodium/JetBrains), session type tracking

Usage

Start the Web Monitor

cd gsd-monitor-web
python run.py

This will:

• Start the server on port 8765 (configurable with --port)
• Display a QR code for mobile access
• Show local and network URLs

Open one of the URLs in your browser to monitor your Claude Code/GSD session.

A handy QR Code is provided for phones. (NOTE: Make sure your firewall allows local network access to the IP & port displayed)

(sample URLs, yours will be different)

Selecting a Session

GSD Usage: You will be shown up to 10 current Claude Code sessions (this system actually monitors Claude with some extra info shown for GSD sessions). Look for the one that is active with your GSD project name (here it is named "TEST2"). Click on it to select that session to monitor.

Claude Code Usage: Click on the active Claude Code session you want to monitor. You will see sessions from Claude Code and Claude plugins in VSCodium, VSCode, etc. The Claude Code version just doesn't show GSD status information (because of course, you aren't using GSD).

The last monitored session (if any) will have a pin icon on it. You can also close old sessions by hoving over the session box and clicking the 'x'. NOTE: Any activity on Claude/GSD will rebuild the session in case you accidently close the wrong one.

Controlling the Web Monitor

Browser Notifications:

• 🔔 Bell - Browser notifications enabled (click to request "Allow" for browser notifications)
• 🔕 Bell with slash - Browser notifications are disabled on this browser

Audio Alerts:

• 🔂 Repeat - Repeating alarm mode: alerts play initially and repeat every 60 seconds while attention is needed
• 🔊 Speaker - Single alert mode: alert plays once when attention is needed
• 🔇 Muted speaker - Sound muted: no audio alerts

Audio Test:

• ▶️ Play - Play a blip sound to make sure alerts will be audible

How It Works

Once hooks are installed, they fire automatically during Claude Code sessions:

Event	What Happens
Session starts	Records start time
Tool executes	Updates status (e.g., "$ git status", "Writing: file.py")
Claude stops	Status turns yellow (waiting for next prompt)
Needs input (60s idle)	Status turns red + browser alert + sound
Needs permission	Status turns red + browser alert + sound

Check Installation Status

python injector.py status

Shows:

• Installed hook scripts
• Hook injection status in settings.json
• Active sessions and their states

Remove Hooks

python injector.py remove

Only removes GSD Monitor hooks - leaves GSD and other hooks intact.

File Structure

gsd-monitor/
├── injector.py              # Main installer script
├── hooks/
│   ├── on_notification.py   # Fires on idle_prompt, permission_prompt
│   ├── on_tool_use.py       # Fires before each tool execution
│   ├── on_stop.py           # Fires when Claude finishes
│   ├── on_session_start.py  # Fires on session start/resume
│   └── state_utils.py       # Shared state file utilities
├── gsd-monitor-web/
│   ├── run.py               # CLI entry point
│   ├── server.py            # FastAPI server
│   ├── state_manager.py     # Session management
│   ├── gsd_reader.py        # GSD project state parser
│   ├── requirements.txt     # Python dependencies
│   └── static/              # Web UI files
├── requirements.txt
└── README.md

After installation:

~/.claude/
├── settings.json              # Modified to include hook references
└── gsd-monitor/
    ├── hooks/                 # Installed hook scripts
    └── state.json             # Live session state

Web Monitor Options

python run.py                    # Start on default port 8765
python run.py --port 9000        # Custom port
python run.py --host 127.0.0.1   # Bind to specific interface (default: 0.0.0.0)
python run.py --no-qr            # Disable QR code display

Limitations

• 60-second delay: The idle_prompt notification fires after 60+ seconds of idle time. The web UI mitigates this with a yellow warning state when Claude stops responding.

Troubleshooting

Hooks not firing

1. Check installation: python injector.py status
2. Verify settings.json has the hook entries
3. Restart Claude Code after installing hooks

Permission errors

Make sure hook scripts are executable:

chmod +x ~/.claude/gsd-monitor/hooks/*.py

Browser notifications not working

Bell icon appears crossed out or disabled:

• You must access via localhost - Browser notifications require a "secure context" (HTTPS or localhost). If you're accessing the monitor via a LAN IP address (e.g., http://192.168.1.23:8765/), notifications will be blocked by the browser. Use http://localhost:8765/ instead, or use audio alerts as an alternative.

Notifications enabled but not appearing:

• Make sure you've granted notification permissions when prompted (click the bell icon)
• Check your browser's notification settings for this site
• Turn off "Do Not Disturb" - On Windows, macOS, and mobile devices, Do Not Disturb / Focus modes will suppress browser notifications. Disable DND to receive alerts.
• On macOS: Check System Settings → Notifications → [Your Browser] is allowed
• On Windows: Check Settings → System → Notifications → ensure both the master "Notifications" toggle is on AND [Your Browser] is on in the app list below

License

MIT - Use as you like.