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>

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>"