GitHub Issue Notes

A Chrome extension to keep personal notes on GitHub Issues and Pull Requests. When a notification arrives long after you subscribed, your note tells you why you were following it. Notes are saved to your own secret Gist and synced across devices.

Features

• Notes on Issues and PRs - Write a note in the sidebar of any GitHub Issue or Pull Request page, right below Notifications
• Stored in your own Gist - Notes are saved to a secret Gist in your GitHub account, not on a server run by the developer. Anyone who has the Gist's URL can see it, so keep the URL to yourself
• Auto-save - Notes are saved a second after you stop typing
• Dark mode - Follows GitHub's dark mode when your GitHub theme is set to dark
• Cross-device sync - Set up the extension with the same GitHub account on another computer to see the same notes

Installation

Chrome Web Store

Install from Chrome Web Store

Build from source

Requires Node.js (CI uses version 22) and pnpm.

1. Clone this repository

   git clone https://github.com/naipaka/github-issue-notes.git
   cd github-issue-notes

2. Install dependencies

   pnpm install

3. Build the extension

   pnpm build

4. Load in Chrome

   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the .output/chrome-mv3 folder

Usage

Step 1: Get a GitHub Personal Access Token (PAT)

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
   • Direct link: https://github.com/settings/personal-access-tokens/new

2. Configure the token:
   • Token name: GitHub Issue Notes (or any name you prefer)
   • Expiration: Choose your preferred expiration
   • Repository access: Select "Public Repositories (read-only)" (Gists don't require repo access)
   • Account permissions: Expand and set Gists to "Read and write"

3. Click "Generate token" and copy the token (you won't see it again!)

Note: Classic tokens with gist scope also work if you prefer.

Step 2: Configure the Extension

1. Click the extension icon in Chrome toolbar, then click "Open Settings"
   • Or right-click the extension icon → "Options"

2. Paste your PAT and click "Save"

Step 3: Connect Gist

1. Click the extension icon to open the popup
2. Click "Connect Gist"

3. Once connected, you'll see "Connected" with a link to your Gist

Note: If you have connected before with the same GitHub account, the extension reuses the Gist it created, so your existing notes appear on this computer too.

Step 4: Start Taking Notes!

1. Navigate to any GitHub Issue or PR page
2. Find the "Personal Notes" section in the sidebar (below Notifications)

3. Type your notes - they auto-save after 1 second of inactivity
4. You'll see "Saving..." then "Saved" to confirm

Permissions

Permission	Purpose
storage	Store your PAT and Gist ID locally in your browser
host_permissions (api.github.com)	Access GitHub Gist API to read/write your notes

Privacy

• PAT: Stored locally in your browser and sent only to the GitHub API. Web pages cannot read it
• Notes: Stored in a secret Gist in your GitHub account. It is not listed publicly, but anyone who has its URL can see it
• No analytics or tracking: The extension talks only to api.github.com and collects no usage data. Only the Issues and PRs you write notes on are recorded, as keys in your Gist

See PRIVACY.md for the full privacy policy.

FAQ

Why do I need a Personal Access Token?

The extension needs to access the GitHub Gist API to store your notes. GitHub requires authentication for this, and a PAT with Gists read/write permission is the minimal permission needed.

Why a Gist?

Browser storage such as localStorage cannot sync your notes between computers, and chrome.storage.sync has a small quota and works only in Chrome. A server of our own would mean keeping your personal notes on the developer's side and adding a sign-in system. A Gist syncs through your GitHub account, needs no backend, works with a token that only has Gist access, and lets you read and edit your notes directly on GitHub.

Where are my notes stored?

Your notes are stored in a secret Gist in your GitHub account. You can view and edit this Gist directly at https://gist.github.com. The file is named github-issue-notes.json.

Can others see my notes?

Only if they have the Gist's URL. The Gist is created as a secret Gist, so it is not listed publicly, but anyone who has its URL can see it. Keep the URL to yourself.

What happens if I uninstall the extension?

Your notes remain in your GitHub Gist. If you reinstall the extension and reconnect with the same GitHub account, your notes will be restored.

Does it work on GitHub Enterprise?

Not currently. The extension only supports github.com.

Development

Tech Stack

• WXT - Web Extension Framework
• React - UI Library
• TypeScript - Type Safety
• Tailwind CSS v4 - Styling
• Vitest - Testing

Commands

pnpm dev          # Start development server (Chrome)
pnpm dev:firefox  # Start development server (Firefox)
pnpm build        # Production build
pnpm compile      # TypeScript type check
pnpm test         # Run tests
pnpm zip          # Create ZIP for store submission

pnpm dev opens Chrome with the extension loaded. Your PAT and Gist settings are kept in .wxt/chrome-data, so you don't need to enter them again after restarting.

Project Structure

entrypoints/
├── background.ts   # Service Worker - Gist API communication
├── content.tsx     # Content Script - Injects UI into GitHub pages
├── options/        # Options page - PAT management
└── popup/          # Popup - Gist connection

components/
└── NoteArea.tsx    # Note input component

utils/
├── messaging.ts    # Type-safe messaging between scripts
├── storage.ts      # Chrome storage wrapper
├── gist.ts         # GitHub Gist API client
├── notes.ts        # Notes data management
└── noteKey.ts      # Extracts the note key (owner/repo#number) from the page URL

tests/              # Vitest tests

Contributing

Contributions are welcome! Please open an issue or pull request. See CONTRIBUTING.md for how to get started.

License

MIT