PR Tour
A guided tour of your pull request.
한국어
An agent skill that turns a GitHub PR into a standalone HTML reading guide. Follow the execution flow, read the real diff, and open the definitions you need without losing your place.
Try the example
The example follows Starlette PR #2041: sending an HTTP denial response before accepting a WebSocket connection.
Five changed files, eight reading steps, thirteen definition previews. Both examples use the same pinned commits. The generated HTML needs no server or network connection; GitHub links are optional.
Install
Codex, Claude Code, and other compatible agents
Use the skills CLI to choose an agent and install the skill:
npx skills add YunSinLee/pr-tour --skill pr-tour
To target Codex explicitly:
npx skills add YunSinLee/pr-tour --skill pr-tour --agent codex
The current skills CLI requires Node.js 22.20 or newer. The skill itself uses Python and Git. You can also copy skills/pr-tour/ into a skill directory supported by your agent, such as ~/.agents/skills/ for Codex.
Claude Code plugin marketplace
/plugin marketplace add YunSinLee/pr-tour
/plugin install pr-tour@pr-tour
Invoke /pr-tour:pr-tour, or ask Claude Code to make an HTML walkthrough of a PR.
This repository provides an installable skill and a Claude Code marketplace. Inclusion in any third-party curated registry is a separate process.
Update an existing installation
For a skills CLI installation, run npx skills update pr-tour and choose the scope you installed into. See the CLI update options.
For the Claude Code marketplace installation, run these commands in your terminal (use the original installation scope if it was not user):
claude plugin marketplace update pr-tour
claude plugin update pr-tour@pr-tour --scope user
Then restart Claude Code or follow its plugin reload prompt. See the plugin update reference. For a manual installation, replace your installed pr-tour skill folder with the latest skills/pr-tour/ from this repository.
Already-generated HTML files keep their embedded renderer. To apply an update, regenerate the HTML with the updated skill and the saved manifest, preserving the pinned commits. Use --overwrite only for the file you intend to replace. See the changelog for release details.
Use it
In Codex, inside the relevant repository:
Use $pr-tour to create an English HTML walkthrough of
https://github.com/Kludex/starlette/pull/2041.
Explain the execution flow, include definition previews, and keep the manifest.
Or ask in Korean:
$pr-tour로 이 PR을 코드 흐름대로 따라 읽는 HTML 가이드를 만들어줘.
한국어로 설명하고, 함수·타입 정의와 생략 코드 펼치기를 포함해줘.
The agent reads the pinned source, authors the reading order and explanations, then runs the bundled builder. The Python script alone does not generate explanations from a PR URL.
By default, the skill keeps the HTML and its manifest together in a unique /tmp/pr-tour-<suffix>/ directory, keeping generated files out of your working directory. On platforms without /tmp, it uses the system temporary directory. It opens the guide and returns links to both files. Temporary files may be cleared by the system; request an output path to keep them somewhere permanent. Updating an existing guide reuses its current paths.
For example: Save the guide and manifest in ~/Documents/pr-tours/starlette-2041/.
What the guide does
- Explains the change for readers without repository or domain context: introduce the problem and unfamiliar terms, then describe the previous and new behavior in plain language. Korean explanations use natural, direct Korean. An explicit language or audience request takes precedence.
- Arranges changes by code flow. A file can appear in more than one step.
- Switches Diff view between Unified and Split. Split shows merge-base code on the left and head code on the right, wrapping long lines. Expanded context and comment selections survive switching; the browser remembers the view when storage is available. On mobile, use ⋯, scroll horizontally, or turn on Wrap lines to fit both sides to the screen.
- Leads with behavioral changes and their effects, adding code mechanics where needed. Adapts explanations to new features, tests, and context.
- Scrolls quickly and smoothly to code when selecting an explanation. Manual input stops the motion, and reduced-motion preferences are respected.
- Explains why the next step follows, with expandable source citations, explicit uncertainty for inferred connections, and a separate label for reading-order moves.
- Shows the explanation before the code by default. Use Layout to switch the two panes; the browser remembers your choice when local storage is available. On phones and narrow screens, Guide / Code tabs show one pane at a time and keep your reading position. Selecting a note opens its focused code; changing steps keeps the current tab.
- Drag either vertical divider to resize adjacent panes on desktop. Widths follow the guide/code panes when reordered and are remembered when browser storage is available. Minimum widths keep each pane usable; smaller windows temporarily clamp widths. Double-click a divider to reset all widths, or focus it and use arrow keys (Shift for larger steps), Home/End, and Enter to reset. Escape cancels an active drag.
- Shows actual additions, deletions, old/new line numbers, and focused line notes.
- On mobile, Next code / Prev code follow each note across steps and bring its lines into view. Expand gives code more room; Guide opens the current explanation, and selecting a note returns to expanded code. The ⋯ tools contain line wrapping, full-file context, jump to focus, and the source link. Guide and desktop navigation still move by step.
- Offers larger mobile navigation controls and a definition preview that fills most of the screen. Phone landscape uses a compact header.
- Colors keywords, strings, comments, and function names in diffs and definition previews. Syntax highlighting works offline for common languages; unsupported file types remain plain text.
Understand the connection to the next step
At the end of a step, Up next explains why the guide moves on. Source cited lets you expand the code behind that explanation, including unchanged wiring outside the diff. Includes inference names what remains unverified. Reading order marks moves such as implementation to tests that help understanding without claiming runtime order.
Each excerpt includes the source side, line numbers, syntax colors, and a link to the pinned commit. The excerpts stay in the offline HTML. The guide-wide connection summary counts authored categories and missing connections; it does not certify execution-path completeness or correctness. The builder verifies citation locations and source, while the agent remains responsible for interpreting the relationship.
The example's test-client connection follows the message queue and discloses the omitted framework wiring. To add connections to an older guide, update its manifest and regenerate the HTML; rebuilding alone does not author new explanations. See the connection format.
Read on mobile
- Choose a step, then tap an explanation note to open its code. Guide / Code tabs keep their reading positions.
- Use Next code / Prev code to follow notes in authored order, including the next or previous step. The selected line moves near the top, even at the end of a file. The footer counts code points; the step picker still counts steps. Steps without notes remain reachable as file changes.
- Tap Expand for more code space. Guide opens the current note; tapping that note returns to expanded code. Collapse restores the header.
- Open ⋯ for Wrap lines, full-file context, jump to focus, or the source link. Wrapping changes the display only. Tap outside or press Escape to close the tools; Escape closes an open definition before leaving expanded reading.
Step links use #step-id and open that step's first note; individual notes do not add browser-history entries. Guide and desktop previous/next navigation moves by step.
Leave comments on code
- Open Comments → Comment on current code, or Add comment in the code tools. You can also start by clicking a line number.
- Select one line, then another line on the same side to select a range. Base and head lines are separate. On mobile, the line-number targets grow while selecting.
- Choose Write comment, enter your feedback, and Save. Edit or delete it in the list, with an undo action immediately after deletion. Click a location to return to its lines, including collapsed context.
- Copy for AI copies concise Markdown with your comments, the PR URL, and links to the exact source lines. It omits source code, comment IDs, and timestamps. When clipboard access is blocked, a selectable text box provides the same text for manual copying.
- Open the same PR snapshot in another environment and use Import JSON to choose a file or paste JSON. Review the new, duplicate, and conflicting counts, then select Import comments. If the same comment ID has different edits, the default keeps the existing version. Compare both versions before choosing to replace it with the incoming one.
Paste the copied comments into your AI conversation and ask which feedback to evaluate or apply. Source links retain the pinned commit, file path, base/head side in the label, and line range. Download JSON keeps a complete backup, including selected source text and metadata, for Import JSON. PR Tour does not send either format to an AI service or post GitHub comments. See the review export formats.
Saved comments live in this browser's storage, separated by PR and source snapshot. They do not modify the HTML or automatically sync between devices or browsers. Storage can be restricted for local files and embedded viewers. Check the displayed storage status and download JSON for durable retention or import it to continue elsewhere. Unsaved editor text can be reopened only while the same page stays open.
If saving detects conflicting changes from another tab, it preserves the stored comments and keeps your current edits in memory. Follow the warning and download JSON before reloading.
Import checks the PR/repository URLs, pinned commits, line ranges, and exact source text. Mismatched or invalid files leave existing comments untouched. Matching IDs, locations, and bodies are skipped as duplicates. Files stay on your device; each import accepts up to 10 MiB and 1,000 comments.
Requirements and limits
To make a guide: an agent that supports skills, Python 3.9+, Git, and access to the repository. The preferred GitHub workflow also uses the authenticated gh CLI. Python tokenization may require a newer interpreter for newer source syntax.
To read a guide: a modern browser with JavaScript enabled. No Python, agent, or account is required. An in-app artifact viewer must allow the embedded JavaScript to run.
The demos are tested offline in Chromium and WebKit, with narrow portrait, tablet, and phone-landscape viewports. These are browser tests, not physical-device or Orca artifact-viewer verification.
The builder checks source reconstruction, line ranges, file coverage, and definition-link offsets. Explanations and symbol meanings still need review. Definition links are authored mappings, not an IDE language server. Every changed file must appear, but the builder cannot prove that every important behavior has been explained. Binary, non-UTF-8, and submodule changes show an explicit preview limitation.
Generated guides include repository source code. Choose an example you can share before publishing its HTML. The bundled example uses public Starlette code and includes its license notice.
Build and contribute
Read the skill workflow and manifest format, then run:
python3 skills/pr-tour/scripts/build_guide.py \
--repo /path/to/repository \
--manifest /path/to/guide.json \
--output /path/to/guide.html
Set "language": "en" or "language": "ko" in the manifest, or pass --language en. Existing files are protected unless you pass --overwrite.
Run the builder regression suite without third-party Python packages:
python3 -m unittest discover -s tests -v
Run syntax-rendering and scroll-animation logic tests with Node.js 20+ (no package installation):
node --test tests/test_syntax.cjs
npm run test:scroll
Run browser regression tests for pane resizing, mobile reading, definition previews, comments, and connection evidence in both demos (Node.js 20+):
npm ci
npx playwright install chromium webkit
npm run test:browser
PR_TOUR_BROWSER=webkit npm run test:browser
Regenerate both public examples from the pinned Starlette commits:
python3 scripts/rebuild_examples.py
The first run fetches the public Git snapshots into .cache/starlette. To use an existing clone that already contains both commits, pass --repo /path/to/starlette. This rebuilds the walkthrough, not the upstream test suite.
Contributions are welcome for reading usability, source-link correctness, and additional UI translations. Include a small public or synthetic reproduction and the relevant checks.
License
MIT for this skill, builder, renderer, and authored explanations. Starlette source embedded in the examples retains its BSD-3-Clause license. This is an independent example, not an endorsement by Starlette.
The bundled highlight.js library retains its BSD-3-Clause license, which is also embedded in generated guides. See its maintenance notes for the pinned version and update checks.
