From claude-commands
Starts a local development server with Flask backend and MCP server, including port selection, cache-busting, auth bypass, and CSS hot-swapping.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-commands:local-dev-serverThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```bash
# Default: random port, background mode, logs in current terminal
./run_local_server.sh
# Non-default port, no log streaming (best for agents/CI)
./run_local_server.sh --no-log-stream
# Force default ports (8081 Flask, 3002 React)
./run_local_server.sh --force-default-port
# Interactive cleanup of existing servers
./run_local_server.sh --cleanup
/var/folders/.../frontend_v1_cache_bust.*)After startup, the script prints the URLs:
| Service | Default Port | Random Port Range |
|---|---|---|
| Flask Backend (serves V1 frontend) | 8081 | 8100–8199 |
| MCP Server | 8001 | 8100–8199 |
| React Frontend (V2) | DISABLED | — |
Append URL params to bypass Firebase auth:
http://localhost:<PORT>/?test_mode=true&test_user_id=test-user-123
With fantasy theme:
http://localhost:<PORT>/?test_mode=true&test_user_id=test-user-123&test_theme=fantasy
# Flask logs
cat /tmp/<repo-name>/<branch-name>/flask_backend.log
# Tail live
tail -f /tmp/<repo-name>/<branch-name>/flask_backend.log
# Find errors
grep -i "error\|500\|traceback" /tmp/<repo-name>/<branch-name>/flask_backend.log | tail -20
The server serves from a cache-bust temp dir. To test CSS changes without restarting:
# Find the active temp dir
find $TMPDIR -maxdepth 1 -name 'frontend_v1_cache_bust.*' -type d
# Copy new CSS into it (server picks up changes immediately — no cache)
cp $PROJECT_ROOT/frontend_v1/themes/fantasy.css /var/folders/.../frontend_v1_cache_bust.XXXXXX/themes/fantasy.css
# Option 1: Kill by PID files
kill $(cat /tmp/<repo-name>/<branch-name>/flask_backend.pid) $(cat /tmp/<repo-name>/<branch-name>/mcp_server.pid)
# Option 2: Interactive cleanup
./run_local_server.sh --cleanup
# Option 3: Find and kill by port
lsof -ti :8054 | xargs kill
Use Playwright to capture themed screenshots:
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page(viewport={"width": 1280, "height": 720})
page.goto("http://localhost:8054/?test_theme=fantasy&test_mode=true&test_user_id=screenshot-user")
page.wait_for_timeout(2000)
page.screenshot(path="/tmp/screenshot.png")
browser.close()
Or use the smoke test runner:
# Against the live server (may hang if theme detection differs)
TEST_BASE_URL=http://localhost:8054 python3 testing_ui/test_smoke_fantasy.py
# Start its own server (most reliable)
python3 testing_ui/test_smoke_fantasy.py
| Issue | Solution |
|---|---|
| Port in use | ./run_local_server.sh --cleanup or lsof -ti :<PORT> | xargs kill |
| Missing API keys | Ensure gcloud is configured with worldarchitecture-ai project |
| Venv creation fails | Delete venv/ and re-run |
| CSS changes not showing | Server serves from cache-bust temp dir; either hot-swap or restart |
| Smoke test hangs on live server | Use direct Playwright script instead (theme detection race condition) |
npx claudepluginhub jleechanorg/claude-commands --plugin claude-commandsConfigures Replit dev workflow: .replit run commands, hot reload for Node/Python/Vite, Webview ports, dev/prod DBs, Replit Agent.
Tests local web applications using Playwright: launches servers, takes screenshots, inspects DOM, and runs automation scripts.
Sets up Vercel local dev server with vercel dev, pulls env vars, enables hot reload, and tests serverless functions/APIs. For fast local iteration on Vercel projects.