What scope is required?

The notifications scope is required to list and mutate notifications.

Which endpoint marks a notification as read?

REST: PATCH /notifications/threads/{summaryId} uses summaryId.

How do I bulk mark as read?

Fetch summaryIds via GraphQL, then batch process with REST DELETE on /notifications/threads/{summaryId} (or similar) as shown in the Bulk Mark Done example.

github:notifications

npx machina-cli add skill bendrucker/claude/notifications --openclaw

Files (1)

SKILL.md

2.1 KB

GitHub Notifications

Manage the inbox via GraphQL (list) and REST (actions). Requires notifications scope.

Listing (Inbox)

Query: graphql/inbox.graphql

gh api graphql -f query="$(cat graphql/inbox.graphql)" \
  --jq '[.data.viewer.notificationThreads.nodes[] | select(.isDone == false)]'

Fields

Field	Description
`id`	GraphQL node ID for mutations
`summaryId`	Numeric ID for REST actions
`isUnread`	Unread status
`isDone`	Done status (hidden from inbox)
`isSaved`	Saved for later
`reason`	`ASSIGN`, `AUTHOR`, `COMMENT`, `MANUAL`, `MENTION`, `REVIEW_REQUESTED`, `SUBSCRIBED`, `CI_ACTIVITY`, `STATE_CHANGE`
`url`	Browser URL (direct, no transform needed)

Actions

REST (use summaryId):

gh api -X PATCH /notifications/threads/{summaryId}                      # Mark read
gh api -X DELETE /notifications/threads/{summaryId}                     # Mark done
gh api -X PUT /notifications                                           # Mark all read
gh api -X DELETE /notifications/threads/{summaryId}/subscription        # Unsubscribe
gh api -X PUT /notifications/threads/{summaryId}/subscription -f ignored=true  # Mute

GraphQL mutations (use id):

gh api graphql -f query='mutation { markNotificationAsUnread(input: {id: "{id}"}) { success } }'
gh api graphql -f query='mutation { markNotificationAsUndone(input: {id: "{id}"}) { success } }'

Filtering

Filter in jq after the GraphQL query:

# By reason
... --jq '[.data.viewer.notificationThreads.nodes[] | select(.isDone == false and .reason == "MENTION")]'

# Unread only
... --jq '[.data.viewer.notificationThreads.nodes[] | select(.isDone == false and .isUnread == true)]'

Bulk Mark Done

gh api graphql -f query='...' --jq '.data.viewer.notificationThreads.nodes[] | select(.isDone == false) | .summaryId' | \
  xargs -I {} gh api -X DELETE /notifications/threads/{}

Source

git clone https://github.com/bendrucker/claude/blob/main/plugins/github/skills/notifications/SKILL.mdView on GitHub

Overview

Manage GitHub notification threads using GraphQL for listing and REST for actions. This skill helps you triage, filter, and bulk-update notifications efficiently, including marking read, done, or unsubscribing. It requires the notifications scope to access and mutate your inbox.

How This Skill Works

Listing uses a GraphQL inbox query to fetch notificationThreads with fields like id, summaryId, isUnread, isDone, and reason. Actions are executed either via REST (using summaryId) to mark read, done, or unsubscribe, or via GraphQL mutations (using id) to toggle unread/undone. Filtering can be done client-side with jq after the GraphQL query.

When to Use It

You need to quickly view all unread or not-done notifications in your GitHub inbox.
You want to mark a single thread as read after reviewing it.
You want to remove or hide processed notifications by marking them done.
You need to unsubscribe or mute noisy threads to reduce future alerts.
You want to filter by reason (e.g., MENTION) or unread status to focus on relevant items.

Quick Start

Step 1: Authenticate with gh and ensure the notifications scope is granted.
Step 2: List inbox threads with a GraphQL query to identify unread/not-done items.
Step 3: Use REST or GraphQL mutations to mark items as read, done, or unsubscribe as needed.

Best Practices

Ensure you have the notifications scope authenticated before attempting listing or actions.
Fetch the inbox with GraphQL first, then perform batch actions via REST to minimize calls.
Use jq filters to narrow results (e.g., by isDone, isUnread, or reason) before actions.
Operate with the correct identifiers: id for GraphQL mutations, summaryId for REST actions.
Test bulk operations on a small subset before applying to all threads.

Example Use Cases

List unread, not-done threads: gh api graphql -f query='... graphene ...' --jq '[.data.viewer.notificationThreads.nodes[] | select(.isDone == false)]'
Mark a single thread as read: gh api -X PATCH /notifications/threads/{summaryId}
Mark a thread as done (remove from inbox): gh api -X DELETE /notifications/threads/{summaryId}
Unsubscribe a thread: gh api -X DELETE /notifications/threads/{summaryId}/subscription
Bulk mark all unread as read (example): gh api graphql -f query='...' --jq '.data.viewer.notificationThreads.nodes[] | select(.isDone == false) | .summaryId' | xargs -I {} gh api -X DELETE /notifications/threads/{}

Frequently Asked Questions

Add this skill to your agents