# Pr Local Preview Maintainer > Use when checking out, running, previewing, reviewing, or validating a GitHub pull request locally in a safe worktree, including PR preview URLs, local screenshots, readiness checks, logs, and cleanup instructions. - Skill: `undertone0809/pr-local-preview-maintainer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add undertone0809/pr-local-preview-maintainer` - Raw SKILL.md: https://api.skillmd.com/api/skills/undertone0809/pr-local-preview-maintainer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: undertone0809 (https://skillmd.com/u/undertone0809) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/undertone0809/pr-local-preview-maintainer --- # PR Local Preview Maintainer Run pull requests in a disposable local worktree and give the user a stable preview link. The point is to let the user review the PR while protecting their current working tree and making UI changes visible. ## Default Workflow ### 1. Preserve the current workspace Start by checking the repository state: ```bash git status --short --branch gh pr view --json number,title,state,headRefName,headRepositoryOwner,url,isCrossRepository ``` If the current worktree has local changes, do not run `gh pr checkout` there. Create or reuse a sibling worktree instead. This avoids overwriting unrelated work and keeps the PR preview easy to remove later. Use a predictable path: ```text /-pr- ``` For this repository, PR 8 should become: ```text /Users/zeeland/projects/rudder-oss-pr-8 ``` If the directory already exists, inspect it before reusing it: ```bash git -C status --short --branch git -C branch --show-current ``` If it is dirty, ask only if the dirty changes conflict with the user's goal. Otherwise, pick a suffixed path such as `-pr--preview`. ### 2. Check out the PR in the worktree Create the worktree from the remote base, then check out the PR branch inside it: ```bash git worktree add --detach origin/main gh pr checkout --branch zeelandc/pr- ``` If `main` is not the base branch, use the PR's actual base ref. Prefer a local branch name that makes the preview purpose clear and follows the user's branch prefix convention when the repository defines one. After checkout, verify: ```bash git status --short --branch ``` ### 3. Install dependencies only when needed Check whether dependencies are present: ```bash test -d node_modules && echo node_modules-present || echo node_modules-missing ``` If missing, install them from the worktree: ```bash pnpm install ``` Report install warnings only when they affect the preview. Routine peer or bin link warnings can be mentioned briefly. ### 4. Choose isolated runtime settings Before starting, inspect occupied ports and existing local runtimes: ```bash lsof -nP -iTCP: -sTCP:LISTEN ``` For Rudder, prefer: ```bash RUDDER_INSTANCE_ID=pr- PORT= RUDDER_EMBEDDED_POSTGRES_PORT= ``` Use `3100` only if it is free and the user clearly wants the default instance. If another Rudder dev runtime is already running, leave it alone and use a separate port and instance ID. Example: ```bash env RUDDER_INSTANCE_ID=pr-8 PORT=3118 RUDDER_EMBEDDED_POSTGRES_PORT=54358 pnpm dev ``` ### 5. Start the preview so it survives hand-off Use `tmux` when available. It keeps the preview alive after the assistant turn ends and gives the user a simple way to inspect logs. ```bash tmux new-session -d -s rudder-pr- -c \ 'env RUDDER_INSTANCE_ID=pr- PORT= RUDDER_EMBEDDED_POSTGRES_PORT= pnpm dev' ``` If `tmux` is not available, use another managed background process and capture logs to `/tmp/-pr-.log`. Do not leave an opaque process running without telling the user how to stop it. ### 6. Wait for readiness Poll the health endpoint or the app's equivalent readiness check: ```bash curl -fsS http://127.0.0.1:/api/health ``` If the app has no health endpoint, use the first meaningful route and check for a successful response. For frontend-only apps, load the dev server URL and confirm it serves HTML. When startup fails, inspect the session logs before returning: ```bash tmux capture-pane -pt rudder-pr- -S -160 ``` Fix straightforward startup issues yourself when they are local environment problems, such as missing dependencies or port conflicts. Do not edit PR source code unless the user asked for a fix. ### 7. Decide whether UI screenshots are required Screenshots are required when any of these are true: - the PR title, files, or user request mentions UI, layout, pages, components, CSS, design, screenshots, visual review, browser behavior, or interaction - changed files live under `ui/`, `desktop/`, frontend route files, component directories, stylesheets, or public assets - the user says they want to "see" the effect Use Browser Use for local browser inspection when available. Capture the important screen or flow after the preview is running. Store temporary screenshots outside the repository, for example: ```text /tmp/rudder-pr--.png ``` For non-UI backend/API PRs, a health check plus a task-specific API smoke check is usually enough. If the user still needs to review manually, provide the URL. ### 8. Hand-off format Keep the final response short and concrete: ```text PR is running in . Open: http://127.0.0.1: Logs: tmux attach -t rudder-pr- Stop: tmux kill-session -t rudder-pr- Health check passed: Screenshots: ``` If screenshots were required but could not be captured, say exactly why and what verification did run. ## Cleanup Requests When the user asks to close, stop, or clean up the preview, stop only the PR preview session and verify its port is free: ```bash tmux kill-session -t rudder-pr- lsof -nP -iTCP: -sTCP:LISTEN ``` Do not remove the worktree unless the user explicitly asks for cleanup. If they do ask to remove it, verify the worktree has no uncommitted changes first. ## Safety Notes - Never use destructive Git commands in the user's main worktree to make a PR checkout succeed. - Do not stop unrelated Rudder dev sessions just because the default port is in use; choose an isolated port instead. - Keep PR preview data isolated with a dedicated `RUDDER_INSTANCE_ID`. - If source edits become necessary, pause and state that the task has shifted from previewing a PR to fixing it.