RCE - Refresh Context Engine

Browser automation with time-travel debugging for AI agents.

RCE provides live browser control, frame-by-frame DOM recording, and session persistence - built specifically for AI-driven web automation with full debugging capabilities.

🎯 Key Features

• Live Browser Control - Navigate, click, type, interact with web apps in real-time
• RRWeb Time-Travel - Frame-by-frame DOM recording with visual replay
• Session Persistence - Login state persists across restarts (OAuth, cookies, localStorage)
• MCP Integration - First-class support for Cursor and other MCP clients
• Fast Actions - 300-500ms per action with optimized IPC
• Multi-Tab Support - Automatic detection and per-tab recording
• Console & Network Logs - Complete debugging context with millisecond timestamps
• Stealth Mode - Bypasses basic bot detection for OAuth flows

🆚 How RCE Differs from Playwright MCP

Feature	RCE	Playwright MCP
Time-Travel Debugging	✅ RRWeb frame-by-frame replay	❌ Screenshots only
Session Persistence	✅ Auth state persists across restarts	❌ Fresh session each time
DOM Mutations	✅ Every keystroke/click captured	❌ State-based snapshots
Performance	⚡ 300-500ms actions	~1-2s actions
Multi-Session	✅ Fixed socket, rapid restarts	❌ Slower restarts
Use Case	AI agents, long-running automation	Testing, one-off scripts

RCE is built for AI agents that need:

• Persistent sessions across many interactions
• Complete debugging context for every action
• Time-travel to understand what went wrong
• Fast, repeated browser control

📦 Packages

This monorepo contains:

• @refresh-dev/rce - CLI tool for browser recording and automation
• @refresh-dev/rce-mcp - Model Context Protocol server for Cursor integration

🚀 Quick Start

For End Users (with Cursor/MCP):

1. Install the CLI:

npm install -g @refresh-dev/rce

2. Add to Cursor MCP config (~/.cursor/mcp.json):

{
"mcpServers": {
"rce": {
"command": "npx",
"args": ["-y", "@refresh-dev/rce-mcp"],
"env": {
"RCE_WORK_DIR": "/path/to/your/project"// Required!
}
}
}
}

Note:RCE_WORK_DIR is required for MCP integration to locate your RCE session.

3. Start RCE in your project:

cd your-project
rce dev --url http://localhost:3000 --serverCmd "npm run dev"

4. Use from Cursor:

Agent: "Navigate to /login and sign in with test credentials"

The MCP tools handle browser automation while RCE records everything!

For Developers (CLI only):

npm install -g @refresh-dev/rce
# Start recording
rce dev --url http://localhost:3000
# In another terminal - execute actions
rce action browser_navigate --json '{"url":"http://localhost:3000/app"}'
rce action browser_click --json '{"selector":"button.submit"}'# Time-travel screenshots
rce frames # List captured frames
rce shot --index 50 # Screenshot at frame 50
rce diff --from 10 --to 50 # DOM diff

🎬 How It Works

Cursor AI Agent
↓
MCP Server (@refresh-dev/rce-mcp)
↓
RCE CLI (rce dev - long-running)
↓
Playwright/Chromium Browser
↓
Your Web App
Everything recorded:
• RRWeb: DOM mutations
• CDP: Screenshots every frame
• Console: All logs
• Network: All requests
• Actions: Every interaction

Storage:

.rce/
├── control.sock ← IPC for live control
├── storage-state.json ← Auth persistence
└── data/<session-id>/
├── rrweb/ ← Frame-by-frame DOM
├── screenshots/ ← Time-travel images
├── logs/ ← Console + network
└── actions/ ← Action timeline

🔧 Configuration

Optional config file (rce.config.json in your project):

{
"url": "http://localhost:3000",
"serverCmd": "npm run dev",
"bootWaitMs": 1500,
"viewport": { "width": 1280, "height": 800 },
"ui": {
"port": 43210
}
}

CLI Flags:

rce dev --url URL # App URL to open
--serverCmd "cmd"# Dev server to start
--headless # Run browser invisibly
--clear-state # Clear saved login/cookies
--port N # UI server port

🛠️ MCP Tools Available

When using with Cursor:

Navigation & Interaction:

• rce_action_navigate - Go to URL
• rce_action_click - Click elements
• rce_action_type - Type into inputs
• rce_action_press-key - Press keyboard keys
• rce_action_hover - Hover over elements

Time-Travel:

• rce_frames - List all captured frames
• rce_shot - Screenshot at specific frame
• rce_diff - DOM diff between frames
• rce_screenshot-latest - Current screenshot

Tab Management:

• rce_tabs - List all browser tabs

🎯 Use Cases

1. AI Agent Testing

"Test the checkout flow: add product to cart, go to checkout, fill form, submit"

RCE records every step, you can replay failures frame-by-frame.

2. Session Recording for Debugging

User reports bug → You have complete recording with console logs, network requests, and DOM state at every moment.

3. Authenticated Testing

Log in once → Session persists → Agent can test authenticated features across many runs.

4. Visual Regression

Compare screenshots at frame N across different builds.

🔐 Security & Privacy

• Storage state contains auth tokens - Add .rce/storage-state.json to .gitignore
• Browser profile at .rce/browser-profile/ - Contains cookies, don't commit
• Recordings may contain sensitive data - Review before sharing

📖 Documentation

• CLI Documentation
• MCP Server Documentation

🤝 Contributing

This is an open-source project under MIT license. Contributions welcome!

📜 License

MIT License - see LICENSE file

🙏 Acknowledgments

Built on:

• Playwright - Browser automation
• RRWeb - Session recording
• Model Context Protocol - AI integration

---

Made by Refresh - Building the first AI app builder that integrates with your internal software.