Screenshot a running Phoenix feature and attach images to a GitHub PR. Builds the frontend, starts Phoenix with env vars, uses agent-browser to capture screenshots, uploads to GCS, and updates the PR body.
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.
agent-browser CLI installed and availablegsutil authenticated with access to gs://arize-phoenix-assets/gh CLI authenticated with the Arize-ai/phoenix repopnpm and uv available for building and running PhoenixThe 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 return 404.
/playgroundStart 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:
PHOENIX_PORT (not --port) to set the port — the CLI doesn't accept a port flagPHOENIX_WORKING_DIR so you don't collide with an existing DB that may have newer migrationssleep 10 && curl -s -o /dev/null -w "%{http_code}" http://localhost:6007/playground should return 200/tmp/phoenix-*.log if it fails — common issues are migration errors (use a fresh working dir) or port conflictsNavigate 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:
wait --load networkidle then wait 2000-3000 after navigation — React apps need time to hydrateRead tool to verify they captured what you intendedUpload 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)
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>
## 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.
# Kill the Phoenix server
kill <PID>
# Close the browser
agent-browser close
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>"