pr-wrangler

PR Wrangler

PR Wrangler is a terminal UI for triaging and acting on GitHub pull requests. It talks to the GitHub API directly through a native Go client (go-github), classifies each PR into actionable states like Fix CI, Address feedback, or Resolve conflicts, and launches task-focused tmux sessions for follow-up work.

Requirements

• Go 1.25+
• tmux and git on PATH
• A GitHub token — obtained via pr-wrangler auth login (OAuth device flow) or supplied through GITHUB_TOKEN / GH_TOKEN
• Optional: golangci-lint, gofumpt

pr-wrangler deliberately does not depend on the gh CLI. It manages its own token so it only ever holds the scopes it actually needs (repo).

Authentication

pr-wrangler has its own auth subcommand backed by GitHub's OAuth device flow:

pr-wrangler auth login    # interactive device flow, stores a scoped token
pr-wrangler auth status   # show current token source and verify it
pr-wrangler auth logout   # remove the stored token

On first auth login you'll be asked for an OAuth App Client ID. To create one (one-time setup at https://github.com/settings/applications/new):

• Application name: anything (e.g. pr-wrangler)
• Homepage URL: any URL
• Authorization callback URL: http://localhost (unused by device flow)
• Check Enable Device Flow

Copy the Client ID and paste it when prompted. It's saved to oauth_client_id in your config file so you won't be asked again. You can also pre-set it via the PR_WRANGLER_CLIENT_ID environment variable or by editing the config directly.

Token resolution order

When the TUI starts (or any subprocess like the Claude agent runs), the token is resolved in this order:

1. GITHUB_TOKEN environment variable
2. GH_TOKEN environment variable
3. Stored token at ~/.config/pr-wrangler/auth.json (or the platform-specific equivalent via os.UserConfigDir())

The stored file is created with 0600 permissions and contains the token, the granted scopes, the GitHub username, and a creation timestamp. pr-wrangler re-exports the resolved token to spawned agents via GITHUB_TOKEN=... so the same identity is used end-to-end.

Development

make build
make run
make test
make check

make run builds ./pr-wrangler and starts the Bubble Tea interface.

CI Validation

Before submitting a pull request, run make check to ensure your changes pass all CI checks:

• Format Check: make fmt-check - Validates code formatting
• Lint: make lint - Runs golangci-lint with configured rules
• Vet: make vet - Runs go vet for static analysis
• Test: make test-race - Runs tests with race detector
• Coverage: Target is 80% code coverage (currently tracked as a warning)

The CI pipeline will automatically run these checks on all pull requests.

Configuration

The app reads config from ~/.config/pr-wrangler/config.yaml (or the platform-specific equivalent — see os.UserConfigDir). If the file is missing, built-in defaults are used and pr-wrangler will surface the resolved path on the loading screen.

Example:

repo_base_dir: /Users/you/projects
service_label_prefix: service:
color_scheme: dracula
cache_enabled: true
oauth_client_id: Iv1.xxxxxxxxxxxxxxxx   # optional; set by `pr-wrangler auth login`
views:
  - name: My PRs
    query: author:@me is:open
    default: true
agent_commands:
  fix-ci: "claude --permission-mode acceptEdits 'The CI checks are failing on this PR: {{pr_url}} - Investigate and fix the issues.'"

Files written to the config dir:

• config.yaml — application config (this file)
• auth.json — stored OAuth token (mode 0600, written by pr-wrangler auth login)
• history.json — persisted PR session history

Set cache_enabled: false to disable both the on-disk PR cache and the short-lived in-memory fetch cache. You can also bypass cache usage for a single launch with pr-wrangler --no-cache.

To clear cached PR data without disabling future cache usage, run:

pr-wrangler cache clear

Use pr-wrangler cache status to inspect cached query entries and pr-wrangler cache path to inspect the exact cache file location.

Color Schemes

Set color_scheme to one of the following values (default: default):