GitHub Integration

TUICommander monitors your GitHub PRs and CI status automatically.

Authentication

TUICommander needs a GitHub token to access PRs and CI status. You have two options:

Option 1: OAuth Login (Recommended)

1. Open Settings > GitHub
2. Click “Login with GitHub”
3. A code appears — it’s auto-copied to your clipboard
4. Your browser opens GitHub’s authorization page
5. Paste the code and authorize
6. Done — the token is stored securely in your OS keyring

This method automatically requests the correct scopes (repo, read:org) and works with private repositories and organization repos.

Option 2: gh CLI

If you prefer, install the gh CLI and run gh auth login. TUICommander will use the gh token automatically.

Token Priority

When multiple sources are available, TUICommander uses this priority:

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. OAuth token (from Settings login)
4. gh CLI token

Requirements

• GitHub authentication (see above)
• Repository with a GitHub remote

PR Monitoring

When you have a branch with an open pull request, the sidebar shows:

PR Badge

A colored badge next to the branch name showing the PR number:

Click the PR badge to open the PR detail popover.

CI Ring

A circular indicator showing CI check status:

The ring segments are proportional to the number of checks in each state. Click to see detailed CI check information.

Diff Stats

Per-branch addition/deletion counts shown as +N / -N next to the branch name.

PR Detail Popover

Click a PR badge or CI ring to open the detail popover. Shows:

• PR title and number with link to GitHub
• Author and timestamps (created, last updated)
• State indicators:
  • Draft/Open/Merged/Closed
  • Merge readiness (Ready to merge, Has conflicts, Behind base, Blocked)
  • Review decision (Approved, Changes requested, Review required)
• CI check details — Individual check names and status
• Labels — With GitHub-matching colors
• Line changes — Total additions and deletions
• Commit count

PR Notifications (Toolbar Bell)

When any branch has a PR event that needs attention, a bell icon with a count badge appears in the toolbar.

Click the bell to see all active notifications in a popover list. Each notification shows the repo, branch, and event type.

Notification Types

Interacting with Notifications

• Click a notification item — Opens the full PR detail popover for that branch
• Click the dismiss (x) button on an item — Dismiss that single notification
• Click “Dismiss All” — Clear all notifications at once

PR Badge on Sidebar Branches

Click the colored PR status badge on any branch in the sidebar to open the PR detail popover directly.

Polling

GitHub data is polled automatically:

• Active window: Every 30 seconds
• Hidden window: Every 2 minutes (reduced to save API budget)
• API budget: ~2 calls/min/repo = 1,200/hr for 10 repos (GitHub limit: 5,000/hr)

Polling starts automatically when a repository with a GitHub remote is active.

Merge State Classification

Review State Classification

Auto-Delete Branch on PR Close

When a PR is merged or closed on GitHub, TUICommander can automatically clean up the corresponding local branch. Configure per-repo in Settings > Repository Settings or set a global default in Settings > General > Repository Defaults.

Safety guarantees:

• The default/main branch is never deleted
• If a branch has a linked worktree, the worktree is removed first
• Uses safe git branch -d — refuses to delete branches with unmerged commits
• Dirty worktrees (uncommitted changes) always escalate to Ask mode, even when set to Auto

Remote-Only Pull Requests

When a branch exists only on the remote (not checked out locally) but has an open PR, it still appears in the sidebar with a PR badge. These “remote-only” PRs support inline accordion actions:

• Checkout — Creates a local tracking branch from the remote
• Create Worktree — Creates a worktree for the branch

PR Detail Popover Actions

Clicking the PR badge on any branch (local or remote-only) opens the detail popover. Available actions:

Post-Merge Cleanup

After merging a PR from the popover, a cleanup dialog appears with checkable steps:

1. Switch to base branch — if the working directory has uncommitted changes, they are automatically stashed. An inline warning shows with an optional “Unstash after switch” checkbox
2. Pull base branch — fast-forward only
3. Delete local branch — closes terminals first, refuses to delete default branch
4. Delete remote branch — gracefully handles “already deleted”

Steps execute sequentially via the Rust backend (not PTY — your terminal may be occupied by an AI agent). Each step shows live status: pending → running → success/error.

Dismiss & Show Dismissed

Remote-only PRs can be dismissed from the sidebar to reduce clutter. A “Show Dismissed” toggle in the sidebar reveals them again.

GitHub Issues

The GitHub panel shows issues alongside PRs in a unified view.

Issue Filter

Control which issues appear using the filter dropdown in Settings > GitHub or directly in the panel:

The filter setting persists across sessions.

Issue Details

Expand an issue to see:

• Labels with GitHub-matching colors
• Assignees and milestone
• Comment count and timestamps (created/updated)

Issue Actions

Troubleshooting

No PR data showing:

1. Check gh auth status — must be authenticated
2. Check repository has a GitHub remote (git remote -v)
3. Check that gh pr list works in the repo directory

Stale data:

• Click the refresh button or switch away and back to the branch
• Polling updates every 30 seconds automatically