claude-gh-monitor
English | 日本語
Claude Code plugin: low-context notifications for GitHub's asynchronous events (PR state changes, GitHub Actions workflow runs) via Claude Code hooks + the Monitor tool.
While you wait for PR reviews / CI results or workflow outcomes after a push, this plugin lets Claude Code keep working on something else — and surfaces only the state changes as one-line notifications in the chat. No more manually re-running gh pr view / gh run watch.
Install
claude plugin marketplace add kawaz/claude-gh-monitor
claude plugin install gh-monitor@gh-monitor
After installation, starting Claude Code in a worktree whose branch is tied to an open PR triggers the SessionStart hook to detect the PR and prompt watch-pr. Right after a push, the PostToolUse hook prompts watch-workflow to watch the workflow runs.
Terms used in this README:
- hook — a script the plugin registers with Claude Code to run automatically on session start or after a tool call (
SessionStart, PostToolUse)
- skill — a Claude Code primitive the assistant can invoke; here it tells Claude to start the Monitor with the right arguments
- Monitor tool — the Claude Code background watcher; each emitted stdout line becomes one chat notification
Quick check after install
# 1. In a worktree whose branch has an open PR:
gh pr list --head "$(git branch --show-current)" # should show your PR
claude # SessionStart hook runs
# → Expect a `watch-pr: <owner/repo>#<N>` Monitor to be running
# 2. Right after a push (any of: git push / jj git push / just push / pkf run push):
# → Expect Claude to start a `watch-workflow: <owner/repo>` Monitor
# → Watch the chat for [run:change] ... status:success|failure ... lines
Requirements
-
GitHub CLI (gh) and jq installed
-
Authenticated via gh auth login with read access to the target repository
gh auth status # current auth status
gh auth login # interactive setup if not authenticated
-
The repository is laid out as a git worktree or a jj workspace
Features
Hook: SessionStart
On session start (startup / resume), the hook detects the open PR tied to the current worktree's branch and asks Claude to start the watch-pr skill. It does nothing on branches without an open PR.
Hook: PostToolUse
When a git push / jj git push / just push / pkf run push succeeds via the Bash tool, the hook asks Claude to start the watch-workflow skill. It stays silent on failures (is_error / interrupted) or non-push commands.
Skill: watch-pr
One persistent Monitor per PR runs watch-pr.sh and emits a single line whenever the PR state changes. The Monitor description follows the watch-pr: <owner/repo>#<N> naming convention to prevent duplicate watchers.
Example emits ([scope:action] key:value format):
[comment:add] user:alice url:https://github.com/owner/repo/pull/N#issuecomment-123 body:"LGTM"
[review:submit] user:alice state:APPROVED
[ci:change] check:Test status:failure url:https://github.com/owner/repo/actions/runs/...
[pr:merge] user:alice commit:abc1234 at:2026-04-23T02:00:00Z
[pr:close]
Skill: watch-workflow
watch-workflow.sh runs as a Monitor and emits a single line whenever a GitHub Actions workflow run changes state. Two modes (DR-0005):
| Mode | When | Exit condition |
|---|
| SHA-pinned (recommended for own work) | Track a specific commit you just pushed. Triggered automatically by the PostToolUse hook | All checks for the SHA reach terminal state + grace window (default 60s) elapses; or --no-match-timeout (default 10m) if no matching run is ever observed |
| Passive (opt-in) | Watch the repo as a whole, including others' pushes. Idle backoff (initial 30s → up to --max-interval) | --timeout elapses (default 24h) or manual stop |
A mode flag is required (--sha <SHA> or --passive); a bare invocation exits 2 as a guard against accidental long-running pollers. SHA-pinned launches are parallel-safe for the same repo (different SHAs use distinct Monitor descriptions and exit naturally); Passive is one-per-repo (DR-0003 reinterpreted as Passive-only). Monitor descriptions follow watch-workflow: <owner/repo>@<sha7> (SHA-pinned) / watch-workflow: <owner/repo> (Passive). A 5-minute lookback from start time is used as the baseline cutoff so fast CI runs are still surfaced on the first poll.
Example emit:
[run:change] workflow:ci.yml id:12345678 status:failure commit:abc1234 branch:main user:kawaz event:push
Action hooks (--on-success / --on-failure)
