marcyhub

Opinionated TUI GitHub PR tracker. See your open pull requests across repositories without leaving the terminal.

Install

npx marcyhub

Or install globally:

npm install -g marcyhub

Prerequisites

• Node.js 20+
• GitHub CLI (gh) — used to open PRs in your browser

Setup

On first run, marcyhub asks for a GitHub fine-grained personal access token. Create one at github.com/settings/tokens with read access to your repositories.

The token and your preferences are stored in ~/.config/marcyhub/config.json.

After entering your token, you'll see a searchable list of your repositories. Select the ones you want to track, and you're on the dashboard.

Usage

marcyhub [--interval <seconds>] [--watch <directory>] [--reset-token]

Flag	Default	Description
--interval	300	Poll interval in seconds
--watch	—	Watch directory for JSON items (can be used multiple times)
--reset-token	—	Clear saved config and re-enter setup

Dashboard

marcyhub (2) │ Last: 2m ago │ Next: 3m │ API: 26/30

[1] Created  [2] Assigned  [3] Mentioned  [4] Review Requested  [Z] zzz  [H] hidden
──────────────────────────────────────────────────────────────────────────────────────

● ◆ #142 ● Fix auth redirect          user/repo-a       2d ago  💬3 alice
  ◆ #89    Add dark mode              org/repo-b        5h ago  💬1 bob
    #301 ● Update deps                user/repo-c       1d ago

↑↓ navigate │ Space select │ \ select activated │ 1-4 category │ Enter open │ z snooze │ Del hide │ / search │ ? toggle hints │ r refresh │ s settings │ q quit

Reading the display

• Yellow ● (first column) — PR needs attention (new comment, CI finished, or snooze expired)
• ◆ — PR is selected
• CI status dot (after PR number, colored) — CI check status for Created category PRs
• 💬N author — Comment count and last commenter
• [Z] zzz / [H] hidden — Visibility toggles for snoozed/hidden PRs (bright when showing, dim when hidden)

The (2) in the status bar shows how many PRs need attention.

Keyboard shortcuts

Key	Action
1 2 3 4 5	Switch category (including Watched)
Tab / Shift+Tab	Cycle categories
↑ ↓	Navigate PR list
Space	Toggle selection on cursor PR
\	Select all activated PRs in current category
Escape	Clear selections and deactivate all PRs in category
Enter	Open selected PRs (or cursor PR) in browser
z	Snooze selected PRs (or cursor PR)
Z	Toggle visibility of snoozed PRs
Backspace / Delete	Hide selected PRs (or cursor PR)
H	Toggle visibility of hidden PRs
/	Enter search mode (filter PRs by title)
?	Toggle keyboard hints visibility
r	Force refresh
s	Go to settings
q	Quit

Search mode

Press / to enter search mode. Type to filter PRs by title. Arrow keys navigate, Space selects, \ selects all visible, Enter opens, Escape exits search.

Activation system

Items that need your attention are "activated" and marked with a yellow bullet. An item activates when:

• Someone comments on a PR (comment count changes)
• CI status transitions from pending/running to a final state (Created category PRs)
• A watched item's status changes
• A snooze timer expires

Acknowledging an item (opening, snoozing, hiding, or pressing Escape) removes the activation marker.

Watched Items

Monitor directories for JSON files that represent attention items (useful for tracking non-PR items):

marcyhub --watch ~/.config/claude-code/items --watch ~/other-items

JSON File Schema

Each .json file in a watched directory should have this structure:

{
  "id": "optional-display-id",
  "status": "pending|running|success|failure|neutral",
  "title": "Required title",
  "source": "Required source identifier",
  "lastUpdated": "2025-02-15T10:30:00Z",
  "action": { "type": "url|command", "value": "..." }
}

• id — Optional display ID shown in the ID column
• status — Status indicator (same as CI status colors)
• title — Required item title
• source — Required source identifier (shown in repo column)
• lastUpdated — Required ISO timestamp
• action — Required action when opened: url opens in browser, command executes in shell

Invalid JSON files or files missing required fields are silently excluded.

Watched items appear in the [5] Watched tab with full feature parity: search, snooze, hide, open, and notifications.

Settings

Press s from the dashboard to configure:

• Minimum snooze time — How long a PR must be snoozed before it can auto-unsnooze (default: 15m)
• Comment notifications — Desktop notification when a PR activates due to new comments
• CI status notifications — Desktop notification when CI finishes on your PRs
• Digest schedule — Times to receive a summary notification of all active PRs
• Change repositories — Return to repo selection

How it works

marcyhub uses the GitHub Search API to find open PRs matching four categories:

• Created — PRs you authored
• Assigned — PRs assigned to you
• Mentioned — PRs where you're mentioned
• Review Requested — PRs where your review is requested

Searches are batched across your tracked repos and run in parallel. Rate limits are checked before each poll cycle. CI status is enriched for Created PRs, and last commenter is fetched for the active category.

Development

git clone https://github.com/marcy/marcyhub
cd marcyhub
npm install
npm run build
npm start

Run tests:

npm test

License

MIT