VV is a UI-first development tool that allows you to run and view multiple versions of the same webapp simultaneously in one browser tab. It provides a tiled view of up to 6 different versions running on different ports, with git orchestration and AI-powered code modifications.
- 🎯 Tiled View: Display up to 6 versions of your webapp in a responsive grid layout
- 🔄 Git Orchestration: Automatic branch management for each pane
- 🤖 AI-Powered Changes: Request code changes using cursor-agent CLI
- 💾 Auto-Commit: Automatically stage and commit all changes after agent completes
- 📊 Status Tracking: Visual indicators for ahead/stale branches
- 🔀 Smart Merging: Sequential merge queue with automatic conflict handling
- 💬 Interactive UI: Collapsible floating windows for each pane
- 🏷️ Auto-Titles: AI-generated titles using Google Gemini
vv/
├── backend/ # Python FastAPI server
│ ├── main.py # Main API server
│ ├── git_ops.py # Git operations
│ └── agent.py # cursor-agent integration
├── frontend/ # React + Vite UI
│ └── src/
│ ├── components/ # UI components
│ ├── hooks/ # React hooks
│ └── lib/ # Utilities
└── 1/, 2/, 3/, 4/, 5/, 6/ # Webapp clones
- Python 3.10+
- Node.js 18+
- cursor-agent CLI installed and in PATH
- Git repositories in folders 1-6
- Each webapp should run on ports 3001-3006
- Navigate to the backend directory:
cd backend- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Create a
.envfile:
echo "WEBAPP_BASE_PATH=$(pwd)/.." > .env- Start the backend server:
python main.pyThe API will be available at http://localhost:8000.
- Navigate to the frontend directory:
cd frontend- Install dependencies:
npm install- Create a
.envfile:
cat > .env << EOF
VITE_API_URL=http://localhost:8000
VITE_GEMINI_API_KEY=your_gemini_api_key_here
EOF- Start the development server:
npm run devThe UI will be available at http://localhost:5173.
Ensure you have 6 clones of your webapp in folders named 1, 2, 3, 4, 5, and 6 at the root of the vv directory. Each should be configured to run on ports 3001-3006 respectively.
-
Start VV: Open
http://localhost:5173in your browser -
Add a Pane: Click the
+button in the bottom-left corner- This creates a new git branch and displays the webapp in a new tile
-
Request Changes: Use the floating window on each tile
- Type your request and press Enter or click Submit
- The first request will generate an AI title for the pane
- Agent responses will stream in real-time
- All changes are automatically staged and committed when the agent completes
-
Merge Changes: Click the "Merge" button on panes marked as "Ahead"
- Multiple merge requests are processed sequentially
- Merges push changes to the main branch
-
Remove Panes: Click the
Xbutton when you have more than one pane- Cannot remove panes with running agents or pending merges
POST /api/panes/{pane_id}/create- Initialize a paneGET /api/orchestration- Get status of all panesPOST /api/panes/{pane_id}/agent- Start cursor-agentGET /api/panes/{pane_id}/agent/stream- SSE stream of agent outputPOST /api/panes/{pane_id}/merge- Queue a mergeGET /api/merge-queue- Get merge queue statusDELETE /api/panes/{pane_id}- Reset a pane
Full API documentation available at http://localhost:8000/docs
cd backend
source venv/bin/activate
uvicorn main:app --reloadcd frontend
npm run devFrontend:
cd frontend
npm run build- Ahead: Branch has commits not in main (shows blue badge)
- Stale: Branch is missing commits from main (shows red badge)
- Agent Running: cursor-agent is currently running (shows yellow badge)
- Ensure Python 3.10+ is installed
- Check that all dependencies are installed:
pip install -r requirements.txt - Verify the
.envfile has the correctWEBAPP_BASE_PATH
- Verify the backend is running on
http://localhost:8000 - Check the
VITE_API_URLin frontend.envfile - Ensure CORS is properly configured in the backend
- Verify cursor-agent CLI is installed:
which cursor-agent - Check that the webapp directories (1-6) exist and are git repositories
- Look at backend logs for detailed error messages
- Ensure your webapps are running on ports 3001-3006
- Check browser console for CORS or security errors
- Verify the iframe sandbox permissions
- Merge conflict resolution is not fully implemented yet
- Merges that have conflicts will fail
- The agent uses cursor-agent CLI which must be separately installed
- Each pane's branch follows the pattern
tmp-{id}-{uuid6}
MIT