Enabling AI Agents to Develop While Confirming Browser Displays in a WSL + OpenCode Environment

When developing web applications with an AI agent, significantly improving efficiency is possible by allowing the AI itself to check browser displays. This article summarizes how to achieve this in a Windows + WSL environment.

Assuming the latest Node.js npx is already installed.

Install Playwright Browser

npx playwright install chromium

npx will automatically download Chromium. It’s large, so it takes some time.

Add MCP to opencode.json

Add MCP definitions to opencode.json at the repository root. Create it if it doesn’t exist.

{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": [".agents/skills", ".opencode/skills"]
  },
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@playwright/mcp@latest",
        "--headless",
        "--caps",
        "vision"
      ],
      "enabled": true,
      "environment": {
        "PLAYWRIGHT_BROWSERS_PATH": "0"
      }
    }
  }
}

Adding –headless makes it run without a display, creating a headless browser.

Create a Skill for Browser Display Verification

Create a skill to check browser displays using this method.

---
name: browser-check
description: Verifies the display of a Rails application running on WSL using the Playwright MCP. Use this when verifying UI changes, responsive displays, themes, console errors, and accessibility. ONLY use when the Playwright MCP is enabled and the Rails server is running.
---

# Skill: browser-check

Verifies the browser display of a Rails application running in the WSL environment using the Playwright MCP.

## Prerequisites

- Playwright MCP is enabled in `opencode.json`
- Rails server is running (`bin/rails server -b 0.0.0.0 -p 3000`)
- Node.js is installed in WSL

## Verification Steps

### 1. Check and Start Rails Server

```bash
# Check if running
pgrep -f "rails server" || bin/rails server -b 0.0.0.0 -p 3000 -d
```

### 2. Check Page Display

Open the target page with `browser_navigate`:

```
browser_navigate → http://127.0.0.1:3000/<target URL>
```

### 3. Take Screenshot of Desktop Display

```
browser_screenshot → Desktop width (1280x720)
```

### 4. Take Screenshot of Mobile Display

Check mobile width for responsive pages:

```
browser_resize → 375x812 (equivalent to iPhone X/11)
browser_screenshot
```

### 5. Check Console Errors

```
browser_console_messages → level: "error"
```

If errors exist, identify and fix the cause.

### 6. Check Network Errors

```
browser_network_requests → Check status codes 4xx/5xx
```

### 7. Check Dark Theme (for applicable pages)

For pages with theme switching, verify both light and dark themes.

### 8. Check Form Operations (for applicable pages)

For pages with forms, verify input and submission flows using `browser_fill_form` and `browser_click`.

### 9. Cleanup

```
browser_close → Close the browser
```

## Verification Checklist

- [ ] Page loads normally
- [ ] No layout issues on desktop width
- [ ] No layout issues on mobile width
- [ ] No console errors
- [ ] No network errors
- [ ] Light/dark themes function normally
- [ ] Form operations work normally (if applicable)
- [ ] Accessibility elements (labels, alt attributes, ARIA) are appropriate

## Notes

- The Playwright MCP browser runs headlessly in WSL
- Not displayed on Windows browsers
- Visual verification is done through screenshots
- With `--caps vision`, coordinate-based clicks are possible

Define Usage for UI Development Agent

We added instructions to the already defined agent “frontend-implementer” responsible for UI development.

---
description: Responsible for public and admin interface. Used for tickets modifying ERB, CSS, Stimulus, accessibility, and responsive design.
mode: subagent
model: opencode-go/deepseek-v4-flash
reasoningEffort: medium
permission:
  edit: allow
  bash: allow
---

You are the frontend implementer for tech_notes. Implement only assigned UI tickets.

Before working, check AGENTS.md, docs/requirements.md, corresponding docs/images, and existing views/CSS/Stimulus implementations. Frontend uses importmap + Stimulus, and does not introduce Node.js toolchains. Reuse existing common layouts for public and admin interfaces, maintaining light/dark themes, responsive displays, keyboard operations, and proper labels/semantics. Use existing PostsHelper helpers for Markdown display.

If requirements change, do not edit docs/requirements.md not included in the ticket without reporting to the parent agent. Do not perform scope-exceeding changes, branch operations, commits, pushes, or PR actions, and preserve existing user changes.

After implementation, run Rubocop, related integration tests, and system tests if needed. If browser execution fails due to environment constraints, report the cause without speculation.

## Browser Verification Using Playwright MCP

After completing UI changes, verify actual displays using the Playwright MCP.

1. Confirm the Rails server is running (start with `bin/rails server -b 0.0.0.0 -p 3000` in the background if not running)
2. Open `http://127.0.0.1:3000/<target page>` with `browser_navigate`
3. Take a screenshot of desktop width (1280x720) with `browser_screenshot`
4. For responsive pages, take screenshots of mobile width (375x812)
5. Check console errors with `browser_console_messages`
6. Fix and re-verify layout issues, theme inconsistencies, or accessibility problems
7. Close the browser with `browser_close` after verification

Verification follows design specifications in `docs/requirements.md` and `docs/images/*.png`.

Completion reports should be in Japanese, briefly describing overview, changed files, executed checks and results, browser verification results, and remaining tasks.

Once you request UI checks, it will be handled. It can also automatically perform necessary actions when needed.