diff --git a/docs.json b/docs.json index 2f4b446..0bb3ce4 100644 --- a/docs.json +++ b/docs.json @@ -67,7 +67,17 @@ }, { "group": "PR Dashboard App", - "pages": [] + "pages": [ + "pr-dashboard/pr-list", + "pr-dashboard/diff-viewer", + "pr-dashboard/chat", + "pr-dashboard/ai-analysis", + "pr-dashboard/insights", + "pr-dashboard/pr-actions", + "pr-dashboard/prompts", + "pr-dashboard/review-modes", + "pr-dashboard/settings" + ] } ] }, diff --git a/pr-dashboard/ai-analysis.mdx b/pr-dashboard/ai-analysis.mdx new file mode 100644 index 0000000..bbfb3a7 --- /dev/null +++ b/pr-dashboard/ai-analysis.mdx @@ -0,0 +1,28 @@ +--- +title: AI Analysis +description: Automated AI-powered code review that surfaces risk, architecture impact, and actionable suggestions. +--- + +AI analysis is the core feature that makes PR Dashboard more than a GitHub client. When you click Analyze (or when auto-analyze is enabled), the app sends the pull request to Claude Code for a structured review. The result is a risk assessment, an architecture impact summary, a test coverage evaluation, and a numbered list of actionable suggestions — all generated from reading the actual code changes in your local repository. + +## What the analysis covers + +The analysis produces several distinct sections. **Risk level** is a single rating — low, medium, high, or critical — with color coding so you can spot dangerous PRs at a glance. **Summary** is a plain-language description of what the PR does and why it matters. **Architecture impact** identifies whether the change affects the structure of your codebase and lists the specific modules involved. **Test coverage** assesses whether the changes are adequately tested and calls out gaps. **Suggestions** are numbered, actionable items — each with a title, a description, and references to the relevant files. + +## Inline suggestions in the diff + +AI suggestions don't only appear in the analysis panel. They also show up inline in the diff viewer, anchored to the relevant lines of code. Each suggestion is color-coded by severity: critical suggestions appear in red, warnings in yellow, general suggestions in blue, and praise in green. This means you can see what the AI thinks while reading the code, rather than having to cross-reference a separate panel. + + + The sidecar service clones the repository locally (if not already cloned) and spawns the Claude Code CLI as a subprocess. Claude reads the PR diff and the surrounding code context using file reading and search tools, then produces a structured JSON response following a specific schema. The analysis is allowed up to 30 turns of tool use, giving Claude enough room to explore the codebase thoroughly before forming its assessment. + + + + Analysis results are cached locally on disk, keyed to the specific PR and its commit SHA. If you re-open a PR that has already been analyzed and no new commits have been pushed, the cached result loads instantly. When new commits arrive after an analysis, the app shows a staleness warning with the number of new commits and changes the Analyze button to "Re-analyze (X new commits)" so you know the cached result may be outdated. + + + + Yes. The Prompts page lets you create custom analysis prompt templates that control what Claude focuses on during review. You can create repo-specific prompts or a default prompt that applies globally. This is useful if your team has specific review criteria — for example, always checking for SQL injection in a web app, or verifying backward compatibility in a library. + + +Analysis requires the Claude Code CLI to be installed and available on your system PATH. If the CLI is not found, analysis will fail with an error message. The analysis also respects the timeout configured in settings (default 120 seconds) — very large PRs may need a higher timeout. diff --git a/pr-dashboard/chat.mdx b/pr-dashboard/chat.mdx new file mode 100644 index 0000000..d74434d --- /dev/null +++ b/pr-dashboard/chat.mdx @@ -0,0 +1,24 @@ +--- +title: Chat +description: Ask follow-up questions about any pull request in a conversational interface powered by Claude. +--- + +The Chat panel lets you have a back-and-forth conversation with Claude about the pull request you're reviewing. It appears as the third tab in the right panel when you're in Deep review mode. Instead of just reading a static analysis, you can ask specific questions — "Why was this file restructured?", "Is this change backward compatible?", "What happens if this function throws?" — and get answers grounded in the actual code. + +## What Claude knows + +When you chat about a PR, Claude has access to the full pull request context: the title, description, author, source and target branches, all changed files with their additions and deletions, and the AI analysis summary if one has been run. Claude also has access to the local clone of the repository, so it can read files, search for symbols, and explore the codebase beyond just the diff to answer your questions accurately. + +## How conversations work + +Messages appear in a familiar chat layout — your messages on the right in blue, Claude's responses on the left in gray with full Markdown formatting. The conversation maintains history for the current PR session, so you can build on previous questions. A "Thinking..." indicator shows when Claude is working on a response. + + + When you see an AI suggestion in the diff viewer and click "Explain comment," the app switches to Deep mode and automatically sends that suggestion as a message in the Chat panel. Claude then explains its reasoning in conversational form, and you can ask follow-up questions from there. This turns a one-line suggestion into a dialogue, which is especially useful when you disagree with the AI or need to understand the nuance behind a recommendation. + + + + Chat history persists for the duration of your current session with a given PR. If you switch to a different PR and come back, or restart the app, the conversation resets. You can explicitly clear a conversation using the clear action. This is intentional — chat is meant for in-the-moment exploration, not as a permanent record. + + +Chat uses up to 10 turns of tool use per response. For very complex questions that require extensive codebase exploration, Claude may need to be more concise in its tool usage compared to the full analysis, which gets 30 turns. diff --git a/pr-dashboard/diff-viewer.mdx b/pr-dashboard/diff-viewer.mdx new file mode 100644 index 0000000..83ae155 --- /dev/null +++ b/pr-dashboard/diff-viewer.mdx @@ -0,0 +1,26 @@ +--- +title: Diff Viewer +description: Read code changes file by file with syntax highlighting, inline comments, and AI suggestions. +--- + +The diff viewer is the central reading surface for code review. It shows all changed files in a unified diff format with syntax highlighting, line-by-line additions and deletions, and surrounding context lines. It appears in both Quick mode (full-width) and Deep mode (left panel), giving you the same reading experience regardless of which review mode you're in. + +## File-by-file navigation + +Changes are organized by file. Each file section shows the file path as a header, and the diff content below it. Added lines are highlighted in green, removed lines in red, and unchanged context lines appear in their normal color. This is the same visual language used by GitHub and most diff tools, so it should feel immediately familiar. + +## Inline comments + +Two types of comments appear directly in the diff, anchored to the relevant lines of code. + +**GitHub comments** show the author's avatar and name alongside the comment text. These are the same comments you'd see on the GitHub PR page, but embedded in the diff so you don't have to context-switch to read them. + +**AI suggestions** from the analysis are also shown inline, color-coded by severity. Critical issues appear with a red accent, warnings in yellow, general suggestions in blue, and praise in green. Each AI suggestion includes an "Explain comment" button that sends the suggestion to the Chat panel for deeper discussion. + + + Code review is fundamentally about reading code and forming opinions about specific lines. Putting suggestions next to the code they refer to means you evaluate them in context rather than jumping back and forth between a list of issues and the diff. The separate Analysis panel still exists for the big-picture view, but the inline suggestions are where the AI feedback is most useful during actual line-by-line review. + + + + Both types of comments are shown together in the diff. An optional comments panel (available as a right sidebar in Quick mode, or as the Comments tab in Deep mode) shows the full GitHub comment thread in a more traditional threaded format if you prefer to read comments that way. + diff --git a/pr-dashboard/insights.mdx b/pr-dashboard/insights.mdx new file mode 100644 index 0000000..88920fe --- /dev/null +++ b/pr-dashboard/insights.mdx @@ -0,0 +1,28 @@ +--- +title: Insights +description: Team analytics and contribution metrics across your repositories over any date range. +--- + +The Insights page is a team-level analytics dashboard that shows contribution and review activity across your followed repositories. It's accessible from the sidebar header and gives engineering leads and team members a quick picture of who's doing what, how much review activity is happening, and how work is distributed across repos. + +## Summary cards + +Four cards across the top show the headline numbers for your selected date range: total PRs merged, total reviews submitted, number of unique contributors, and number of active repositories. These give you an at-a-glance health check — if reviews are dropping or a repo has gone quiet, you'll see it here. + +## Leaderboard + +Below the summary cards, a sortable table ranks contributors by activity. Columns include the contributor's name and avatar, the number of PRs they've merged, the number of reviews they've submitted, and their total contributions. Click any column header to sort ascending or descending. This is useful for spotting who's carrying a heavy review load or who might need to pick up more reviews. + +## Repository insights + +A per-repository breakdown shows how many PRs and reviews each repo has seen during the selected period, along with the top contributors for that repo. This helps identify which parts of the codebase are seeing the most activity and whether review coverage is evenly distributed. + +## Filtering and sharing + +A date range picker at the top lets you set a custom "from" and "to" date (defaulting to the last 30 days). A repository selector lets you narrow the view to specific repos. A share button captures the entire Insights page as a PNG image and opens it in your file explorer, making it easy to drop into a Slack message or a team retrospective. + + + The app queries GitHub's API for merged pull requests and review events within your selected date range and repositories. All calculations happen locally — nothing is sent to a third-party analytics service. The data refreshes automatically when you change the date range or repository selection. + + +Insights only reflects activity in the repositories you follow. If a teammate's contributions don't appear, make sure the relevant repos are in your followed list. diff --git a/pr-dashboard/pr-actions.mdx b/pr-dashboard/pr-actions.mdx new file mode 100644 index 0000000..442dc28 --- /dev/null +++ b/pr-dashboard/pr-actions.mdx @@ -0,0 +1,28 @@ +--- +title: PR Actions +description: Take action on pull requests without leaving the app — approve, manage reviewers, check CI, and more. +--- + +The PR header and stats bar provide a set of actions that let you manage a pull request without switching to GitHub in the browser. These are the most common operations you'd perform during or after a code review, consolidated into the app so your review workflow stays uninterrupted. + +## Header actions + +The header bar sits above the review content and includes several action buttons. **Analyze** triggers an AI analysis of the PR (or re-analysis if one has already been run). **Open on GitHub** launches the PR page in your default browser for anything the app doesn't cover. The **Actions dropdown** contains three operations: Approve (with an optional message and GIF picker), Rebase (if the PR branch is behind the base branch), and Close PR (with a confirmation step). + +## CI status + +The stats bar shows a colored dot for the overall CI status — green for passing, red for failing, yellow for in-progress, and orange for mixed results. Clicking on it expands a detailed view of every check run, sorted with failures first. Each check shows its name, status, and conclusion, with a link to the full check details on GitHub. If any checks have failed, a "Re-run failed checks" button appears so you can retry without leaving the app. + +## Review management + +The stats bar also displays review status at a glance: how many approvals and how many "changes requested" reviews have been submitted, each with the reviewer's avatar. Separately, requested reviewers who haven't yet responded are shown with their avatars. An "Add reviewer" button opens a searchable popover of repository collaborators so you can assign additional reviewers. + + + Clicking Approve opens a dialog where you can write an optional review message. There's also a GIF picker if you want to celebrate a great PR. Submitting the dialog posts an approving review to GitHub via the API, the same as clicking "Approve" on the GitHub web interface. + + + + When the PR branch has commits on the base branch that it hasn't incorporated yet, a yellow badge appears in the stats bar showing how many commits it's behind. This is a signal that the PR may need a rebase before merging — which you can trigger directly from the Actions dropdown. + + +Branch name is displayed in the stats bar with a copy button next to it. Clicking the copy button copies the full branch name to your clipboard, which is useful for checking out the branch locally. diff --git a/pr-dashboard/pr-list.mdx b/pr-dashboard/pr-list.mdx new file mode 100644 index 0000000..185604e --- /dev/null +++ b/pr-dashboard/pr-list.mdx @@ -0,0 +1,28 @@ +--- +title: PR List +description: Browse and filter pull requests from all your followed repositories in one place. +--- + +The PR list is the left sidebar of the app and your starting point for every review session. It pulls open pull requests from all the GitHub repositories you follow and presents them in a single, searchable list so you never have to hop between browser tabs to figure out what needs your attention. + +## Two tabs, two jobs + +The sidebar splits into **To Review** and **My PRs**. "To Review" shows pull requests from others that are waiting on you. "My PRs" shows your own open pull requests so you can keep an eye on CI status, review progress, and whether anything has fallen behind. + +## Finding the right PR + +A search box at the top filters by PR title, repository name, author, or PR number (type `#123` to jump straight to a number). Below that, a repository dropdown lets you narrow the list to one or more repos, and a sort toggle flips between newest-first and oldest-first ordering. These filters combine, so you can search for a keyword within a specific repo sorted however you like. + +## What each PR item shows + +Every item in the list displays the author's avatar, the PR title, the repository name, the PR number, and the number of changed files. A small colored dot indicates CI status at a glance — green for passing, red for failing, yellow for in-progress. If an AI analysis is currently running for that PR, a spinning indicator appears on the item so you know work is happening in the background. + + + The app polls GitHub at a configurable interval (default 60 seconds) to fetch the latest pull requests. You can also hit the refresh button in the sidebar header to trigger an immediate update. When auto-analyze is enabled in settings, any newly discovered PRs are automatically queued for AI analysis as soon as they appear. + + + + When new pull requests arrive during a poll, the app sends a desktop notification. Clicking the notification selects that PR and switches directly to the review view. This means you can leave the app running in the background and get alerted when something needs your attention. + + +If the GitHub fetch fails — for example due to a network issue or an expired token — a red error banner appears at the top of the PR list. The banner is dismissible and the app will retry on the next poll cycle. diff --git a/pr-dashboard/prompts.mdx b/pr-dashboard/prompts.mdx new file mode 100644 index 0000000..21e9125 --- /dev/null +++ b/pr-dashboard/prompts.mdx @@ -0,0 +1,24 @@ +--- +title: Prompts +description: Create and manage custom prompt templates that control what the AI analysis focuses on. +--- + +The Prompts page lets you write reusable prompt templates that shape how Claude analyzes your pull requests. Instead of relying on a single generic review prompt, you can create templates tailored to specific repositories, coding standards, or review criteria — and set a default that applies to all analyses. + +## The editor + +The page is split into two panels. The left panel lists your saved prompts with their names, last-updated timestamps, and a star icon indicating which one is the default. The right panel is a rich text editor powered by Tiptap with a formatting toolbar (bold, italic, headings, lists, code blocks). You write your prompt in natural language, describing what you want Claude to pay attention to during analysis. + +## Default prompt + +Starring a prompt marks it as the default, meaning it will be used for all AI analyses unless a repo-specific prompt exists. You can change the default at any time by starring a different prompt. Having a sensible default — for example, one that emphasizes your team's coding standards and common pitfalls — ensures every analysis is at least somewhat tailored to how your team works. + + + When the app runs an AI analysis, it includes the active prompt template as part of the instructions sent to Claude. The prompt shapes what Claude focuses on — for example, a prompt that says "pay special attention to SQL injection risks and authentication checks" will produce an analysis that emphasizes security, while one focused on "performance and memory usage" will surface different issues. The prompt supplements (rather than replaces) the base analysis structure, so you always get risk level, summary, and suggestions regardless of what your prompt says. + + + + Yes. Custom per-repo analysis prompts can be stored in the app's data directory under a prompts folder, named by the repository's owner and name. When an analysis runs for that repo, the repo-specific prompt takes priority over the default. This is useful if you maintain repositories with very different review needs — a security-sensitive backend service versus a design system, for example. + + +Deleting a prompt that is currently set as the default will remove the default. Make sure to star another prompt if you want analyses to continue using a custom template. diff --git a/pr-dashboard/review-modes.mdx b/pr-dashboard/review-modes.mdx new file mode 100644 index 0000000..54f5974 --- /dev/null +++ b/pr-dashboard/review-modes.mdx @@ -0,0 +1,32 @@ +--- +title: Review Modes +description: Three review modes let you match the depth of your review to the complexity of the change. +--- + +When you select a pull request, the main content area opens in one of three review modes — Intent, Quick, and Deep. Each mode is designed for a different stage of the review process, and you can switch between them at any time using the toggle buttons in the PR header bar. + +## Intent mode + +Intent mode is the overview. It answers the question "should I care about this PR?" without making you read a single line of code. You see the PR title, author, change statistics (additions, deletions, file count), branch name, CI status, and review status all in one screen. If an AI analysis has been run, it appears here too — showing the risk level, a plain-language summary, architecture impact, test coverage assessment, and a list of suggestions. This is the mode you use to triage your review queue quickly. + + + Intent mode is designed around the idea that you want a fast, high-level understanding of a PR. The AI analysis is the most valuable part of that understanding, so the app automatically triggers it when you open a PR in Intent mode (if it hasn't been run already). This saves you from having to remember to click Analyze every time. + + +## Quick mode + +Quick mode maximizes screen space for the diff. A collapsible banner at the top shows the risk level and summary from the AI analysis, but the rest of the screen is dedicated to a full-width unified diff viewer. You see changes file by file with syntax highlighting, inline GitHub comments, and inline AI suggestions color-coded by severity. An optional comments panel can slide in from the right if you need to see the full comment thread. + +This is the mode you use when you already know the PR is worth reviewing and you want to read the code efficiently. + +## Deep mode + +Deep mode splits the screen into two panels. The left side (roughly 60% width) shows the same diff viewer from Quick mode. The right side (roughly 40% width) is a tabbed panel with three tabs: Analysis, Comments, and Chat. Analysis shows the full AI review. Comments shows the GitHub comment thread. Chat lets you have an interactive conversation with Claude about the PR. + +This is the mode you use for complex or high-risk changes where you need to dig in, ask questions, and cross-reference the AI analysis while reading the code. + + + When you see an AI suggestion in the diff and want more context, clicking "Explain comment" on that suggestion automatically switches to Deep mode and sends the suggestion to the Chat tab as a question. Claude then explains its reasoning with the full PR context available. This bridges the gap between a quick inline suggestion and a deeper understanding of why the AI flagged something. + + +The review mode you choose is per-session — the app does not persist your last-used mode. It defaults to Intent mode each time you select a new PR. diff --git a/pr-dashboard/settings.mdx b/pr-dashboard/settings.mdx new file mode 100644 index 0000000..360fccb --- /dev/null +++ b/pr-dashboard/settings.mdx @@ -0,0 +1,32 @@ +--- +title: Settings +description: Configure GitHub authentication, repository storage, analysis behavior, and appearance. +--- + +The Settings page handles initial setup on first launch and ongoing configuration changes afterward. It's where you connect your GitHub account, tell the app where to store cloned repositories, and tune behavior like polling frequency and analysis timeouts. + +## GitHub authentication + +The app uses GitHub's device flow for authentication — you click a button, get directed to GitHub to authorize the app, and the token is stored locally. Your avatar and username appear once connected, confirming the account. You can sign out at any time, which clears the stored token. + + + Device flow is a standard OAuth pattern that doesn't require you to generate and paste a token manually. It also means the app never sees your GitHub password. The trade-off is that it requires a brief trip to the browser during setup, but after that the token is stored locally and refreshed automatically. + + +## Repository configuration + +The **repos directory** setting tells the app where to clone repositories on your local filesystem. The app needs local clones to run AI analysis, since Claude reads the actual files rather than working from the GitHub API alone. A folder picker dialog makes it easy to choose the right location. + +## Analysis and polling + +**Claude timeout** controls how long the app will wait for an AI analysis to complete before giving up (default: 120,000 ms / 2 minutes). Increase this for very large repositories or PRs with many changed files. **Poll interval** sets how often the app checks GitHub for new or updated pull requests (minimum 30 seconds, default 60 seconds). **Auto-analyze** is a toggle that, when enabled, automatically runs AI analysis on every new PR that appears during polling — useful if you want analysis results ready before you even open a PR. + +## Appearance + +A theme selector lets you choose between Light, Dark, or System (follows your OS preference). The app uses OKLCH color space for its theme, which means colors are perceptually uniform across light and dark modes. + +## Testing + +A "Send Test Notification" button lets you verify that desktop notifications are working correctly. This is helpful during initial setup to confirm your OS notification permissions are configured. + +Settings are stored locally in your system's application data directory. On macOS this is ~/Library/Application Support/pr-dashboard/. No configuration data is sent to any external service.