visual-dev-loop

name	visual-dev-loop
description	Automated visual development loop: run app, preview in browser, screenshot, inspect, fix, repeat until done. Uses Chrome DevTools MCP for inspection + agent-browser for annotated screenshots + portless for stable dev URLs.

Visual Development Loop

Use this skill when developing frontend/UI features that need visual verification. The agent runs an automated loop: build → preview → screenshot → inspect → fix → repeat until the task is complete.

Tooling Overview

Tool	Purpose
portless	Run dev server with named URL: https://myapp.localhost
chrome-devtools MCP	Navigate, screenshot, snapshot, inspect console, network, performance
agent-browser MCP	Annotated screenshots (numbered labels), visual diff, React tree inspection, Web Vitals

Port-Specific Guidance

When running portless as a Bash command, use the PORT env var if port 443 is unavailable:

PORT=443 portless myapp npm run dev

Portless reads package.json "dev" script automatically. Just run:

portless
# or
portless myapp next dev

This produces https://myapp.localhost (or <project-name>.localhost).

Dev Loop Protocol

Step 1: Start Dev Server

# In project with package.json:
portless

# Or with explicit name and command:
portless <app-name> <dev-command>

The app is now at https://<app-name>.localhost.

Step 2: Open Browser & Navigate

Use chrome-devtools to open the app:

chrome-devtools new_page https://<app-name>.localhost

Step 3: Inspect the UI

Using chrome-devtools (primary):

chrome-devtools take_screenshot            — full page screenshot
chrome-devtools take_snapshot              — accessibility tree with refs
chrome-devtools list_console_messages      — check for errors/warnings
chrome-devtools list_network_requests      — verify API calls, no 4xx/5xx
chrome-devtools lighthouse_audit           — performance/accessibility audit

Using agent-browser (when visual context is needed):

agent-browser screenshot --annotate        — screenshot with numbered labels
agent-browser snapshot -i                  — interactive elements only
agent-browser get title                    — current page title
agent-browser get url                      — current URL

Step 4: Analyze Issues

Compare what you see against the task requirements:

• Visual issues (layout, styling, missing elements) → from screenshots
• Console errors → from chrome-devtools list_console_messages
• Network failures → from chrome-devtools list_network_requests
• Accessibility violations → from lighthouse_audit or take_snapshot

Step 5: Fix Code

Edit the source files based on findings.

Step 6: Reload & Re-inspect

chrome-devtools navigate_page (reload)
# Wait for page to load
chrome-devtools take_screenshot
chrome-devtools list_console_messages

Step 7: Loop Until Done

Repeat steps 4-6 until all issues are resolved.

Agent-Browser Specific Workflows

Annotated Screenshots for Visual Reference

agent-browser navigate_page https://myapp.localhost
agent-browser screenshot --annotate

Produces a screenshot with @e1, @e2, etc. labels overlaid on interactive elements.

Visual Regression Diff

agent-browser screenshot baseline.png
# ... after changes ...
agent-browser screenshot current.png
agent-browser diff screenshot --baseline baseline.png --output diff.png

React Component Inspection

agent-browser new_page https://myapp.localhost --enable react-devtools
agent-browser evaluate_script "agent_browser_react_tree()"

Chrome DevTools Specific Workflows

Full Inspection (Every Loop)

1. take_screenshot                  — visual capture
2. take_snapshot                    — accessibility tree with element refs
3. list_console_messages (types: error, warn) — JS errors
4. list_network_requests (resourceTypes: xhr, fetch) — API call status

Performance Check (When Loading is Slow)

1. performance_start_trace (reload: true)
2. Wait for trace to complete
3. performance_analyze_insight — get performance recommendations

Mobile/Responsive Testing

1. emulate viewport "375x667x2,mobile"
2. take_screenshot
3. resize_page 1440 900
4. take_screenshot

Loop Termination Criteria

The loop stops when ALL criteria are met:

• Application loads without console errors
• All network requests return 2xx/3xx
• UI matches requirements visually (verified via screenshot)
• Accessibility snapshot shows correct elements
• No layout/rendering issues visible

If after 10 iterations the task is not complete, stop and report remaining issues.

Common Pitfalls

1. Port already in use → Kill existing process with kill $(lsof -ti:PORT) or use different port
2. portless permission → First run requires sudo for port 443 on macOS/Linux: sudo portless trust
3. Chrome not starting → Ensure Chrome is installed. chrome-devtools-mcp auto-downloads Chrome for Testing
4. agent-browser not installed → npm install -g agent-browser && agent-browser install
5. Screenshot too large → chrome-devtools-mcp is configured with --screenshot-max-width 1200 to reduce token usage
6. State loss on reload → If app state resets, use chrome-devtools evaluate_script to re-hydrate state after reload