needle

TUI that shows the few PRs that need you: review requests, failing CI, and long-running checks.

Install

cargo install needle-cli

This installs the needle binary.

Quick start

Demo mode (no GitHub token required):

needle --demo

Real mode (requires NEEDLE_GITHUB_TOKEN or GITHUB_TOKEN):

export NEEDLE_GITHUB_TOKEN=ghp_...
# or
export GITHUB_TOKEN=ghp_...
needle

Options

• --days <N>: only include PRs updated in the last N days (default: 30)
• --demo: run with diverse fake data
• --org <ORG>: only show PRs in these orgs/users (repeatable or comma-delimited)
• --include <owner/repo>: only show these repos (repeatable or comma-delimited)
• --exclude <owner/repo>: hide these repos (repeatable or comma-delimited)
• --include-team-requests: include PRs requested to teams you are in (default: user-only)
• --bell: ring terminal bell when a PR enters NEEDS YOU or when CI fails
• --hide-pr-numbers: hide PR numbers column
• --hide-repo: hide repository column
• --hide-author: hide author column
• --no-cache: start empty (skip cached PRs) and rely on fresh refresh
• --purge-cache: delete the cache DB before starting (also works with --demo)

needle --days 7

Configuration File

Needle automatically creates a config file at ~/.config/needle/config.toml on first run. All CLI options can be set as defaults in this file:

# Only include PRs updated in the last N days
days = 14

# Only show PRs from these orgs/users
org = ["my-company", "my-username"]

# Exclude noisy repos
exclude = ["my-company/legacy-repo"]

# Ring terminal bell on important events
bell = true

# Auto-refresh intervals (seconds)
refresh_interval_list_secs = 120
refresh_interval_details_secs = 15

CLI arguments always override config file values.

Pinned PRs

Press p in list view to pin/unpin a PR. Pinned PRs appear in a dedicated 📌 PINNED section at the top of the list, regardless of their score. Pin state persists across sessions.

Requirements

• Rust (stable)
• A GitHub Personal Access Token in NEEDLE_GITHUB_TOKEN or GITHUB_TOKEN

Get a GitHub token

Needle uses the GitHub API, so you’ll need a Personal Access Token.

1. Go to https://github.com/settings/tokens?type=beta and create a Fine-grained token.
2. Choose the account/organization that owns the repos you want to scan.
3. Set Repository access to “All repositories” (or select specific repos).
4. Add Pull requests: Read-only permissions.
5. Copy the token and export it:

export NEEDLE_GITHUB_TOKEN="ghp_..."
# or
export GITHUB_TOKEN="ghp_..."

Note

If both are set, NEEDLE_GITHUB_TOKEN takes priority.

Add it to your bashrc/zshrc for future usage.

What it shows

Included PRs:

• PRs authored by you
• PRs where you are explicitly requested as a reviewer (User)
  (team review requests are ignored unless --include-team-requests)

For each PR it computes:

• Latest commit SHA
• CI state (success/failure/running/none)
• Review request state (requested/approved/none)
• A hard-coded score → sorted desc → grouped into categories

Controls

List view:

• ↑ / ↓: move selection
• Enter: open selected PR in default browser
• Tab: open details view
• p: pin/unpin selected PR
• /: filter mode (type to filter by repo/title/author/#)
  • Esc: exit filter mode + clear filter text
  • Ctrl+n: toggle "only NEEDS YOU"
  • Ctrl+c: toggle "only failing CI"
  • Ctrl+v: toggle "only review requested"
  • Ctrl+x: clear all filters
• ?: help (explains what each section means)
• r: refresh now (shows shimmer while refreshing)
• q: quit

Details view:

• ↑ / ↓: select CI check
• Enter: open selected CI check page (falls back to PR URL)
• f: open first failing CI check (falls back to PR URL)
• Tab: back to list
• r: refresh now
• q: quit

Details view CI checks

In details view you get a list of CI steps (check runs / status contexts):

• ✅ success
• ❌ failed
• 🟡 running (shows “running for …” when startedAt is available)

Refresh behavior

• Fetches on startup in the background (UI shows cached data immediately).
• Manual refresh: r
• Auto refresh in list view: every 3 minutes
• Auto refresh in details view: every 30s
• Manual refresh resets the auto-refresh timer.
• No background async tasks beyond the single refresh worker thread.

Scoring

• Single-screen list, visually grouped by derived category:
  • NEEDS YOU (score >= 40)
  • READY TO MERGE (your PR, CI green, no blockers)
  • DRAFT (draft PRs; shown separately and dimmed)
  • NO ACTION NEEDED (0..39)
  • WAITING ON OTHERS (< 0)
• Empty sections are hidden.
• Draft rows are dimmed.
• No scrolling beyond terminal height (truncates to fit).
• Uses cached SQLite data to render immediately, then refreshes in the background.

Each PR gets a score (higher = more urgent):

+50  review requested from user
+40  CI failed AND state changed since last_seen
+20  CI running longer than 10 minutes
+15  approved but unmerged for >24h
-20  waiting on others (no review requested, CI green, not approved)
-30  CI failed but unchanged since last_seen

Sort:

• Score desc
• Then by updated timestamp desc

Troubleshooting

• Missing token: set GITHUB_TOKEN.
• Not a TTY: run in an interactive terminal (not a non-tty runner).

License

MIT. See LICENSE.