Phoenix PR Screenshot

Capture screenshots of the Phoenix UI to visually document a feature in a pull request. This skill handles the end-to-end workflow: build, launch, screenshot, upload, and attach to PR.

Prerequisites

agent-browser CLI installed and available
gsutil authenticated with access to gs://arize-phoenix-assets/
gh CLI authenticated with the Arize-ai/phoenix repo
pnpm and uv available for building and running Phoenix

Workflow

Step 1: Build the frontend

The Phoenix backend serves the built frontend from src/phoenix/server/static/. Build it from the app/ directory:

cd <repo-root>/app
pnpm install   # only if node_modules is missing
pnpm run build

This compiles the React app and copies static assets into the Python server's static directory. Without this step, page routes like /playground return 404.

Step 2: Start Phoenix

Start the Phoenix backend with any env vars the feature requires. Always use a fresh working directory to avoid DB migration conflicts in worktrees:

PHOENIX_PORT=6007 PHOENIX_WORKING_DIR=/tmp/phoenix-screenshot-demo <OTHER_ENV_VARS> uv run phoenix serve &

Key points:

Use PHOENIX_PORT (not --port) to set the port — the CLI doesn't accept a port flag
Use a temp PHOENIX_WORKING_DIR so you don't collide with an existing DB that may have newer migrations
Wait for the server to be ready: sleep 10 && curl -s -o /dev/null -w "%{http_code}" http://localhost:6007/playground should return 200
Check /tmp/phoenix-*.log if it fails — common issues are migration errors (use a fresh working dir) or port conflicts

Step 3: Screenshot with agent-browser

Navigate to the relevant page, interact with UI elements to show the feature, and capture screenshots:

# Open the page
agent-browser open http://localhost:6007/playground

# Wait for React to fully render
agent-browser wait --load networkidle
agent-browser wait 3000

# Get interactive element refs
agent-browser snapshot -i
# Output shows refs like: button "OpenAI gpt-4o" [ref=e33]

# Interact to reveal the feature (e.g., open a dropdown)
agent-browser click @e33
agent-browser wait 1000

# Capture the screenshot
agent-browser screenshot
# Output: Screenshot saved to /Users/.../.agent-browser/tmp/screenshots/screenshot-<timestamp>.png

Tips:

Always wait --load networkidle then wait 2000-3000 after navigation — React apps need time to hydrate
Re-snapshot after any click that changes the DOM (refs get invalidated)
Take multiple screenshots to tell a story (before/after, dropdown open, etc.)
View screenshots with the Read tool to verify they captured what you intended

Step 4: Upload to GCS

Upload screenshots to the shared PR assets bucket, prefixed with the PR number for organization:

gsutil cp /path/to/screenshot.png gs://arize-phoenix-assets/pull-requests/<PR_NUMBER>-<descriptive-name>.png

Naming convention: <PR_NUMBER>-<descriptive-name>.png (e.g., 11986-playground-loaded.png, 11986-provider-dropdown.png)

Step 5: Update the PR body

Add the GCS-hosted images to the PR description using gh pr edit:

gh pr edit <PR_NUMBER> --body "$(cat <<'EOF'
## Summary
<existing summary>

## Screenshots
<description of what's shown>

![descriptive-alt-text](https://storage.googleapis.com/arize-phoenix-assets/pull-requests/<PR_NUMBER>-<name>.png)

## Test plan
<existing test plan>
EOF
)"

Always preserve the existing PR body content — read it first with gh pr view <PR_NUMBER> --json body -q .body, then add the Screenshots section.

Step 6: Cleanup

# Kill the Phoenix server
kill <PID>

# Close the browser
agent-browser close

Removing screenshots

To remove previously uploaded screenshots:

# Delete from GCS
gsutil rm gs://arize-phoenix-assets/pull-requests/<PR_NUMBER>-<name>.png

# Update PR body to remove the image references
gh pr edit <PR_NUMBER> --body "<updated body without screenshot section>"

phoenix-pr-screenshot