Multi-Monitor Support
Automate workflows across multiple displays with Qontinui Runner
Overview
Qontinui Runner provides full support for multi-monitor setups, allowing you to target specific displays or automate across multiple screens simultaneously. Whether you have a dual-monitor setup, a triple-monitor workstation, or an ultrawide display, the Runner handles coordinate mapping and screen capture seamlessly.
Key Capability: The Runner can capture and automate across the bounding region of multiple selected monitors, treating them as a unified workspace.
How Multi-Monitor Works
Virtual Desktop Coordinate System
Windows (and other operating systems) use a 'virtual desktop' coordinate system where all monitors are combined into one large coordinate space.
- •The primary monitor is typically at position (0, 0)
- •Other monitors have positions relative to the primary
- •Monitors to the left may have negative X coordinates
- •Monitors above may have negative Y coordinates
Example: Example: Left monitor at (-1920, 0), Primary at (0, 0), Right at (1920, 0)
Monitor Detection
The Runner automatically detects all connected monitors and their properties:
- •Monitor index (0, 1, 2, etc.)
- •Physical position (x, y coordinates)
- •Resolution (width x height)
- •Primary monitor designation
- •Position labels (left, middle, right)
Bounding Region Capture
When multiple monitors are selected, the Runner captures the bounding rectangle:
- •Calculates minimum X and Y across all selected monitors
- •Calculates maximum X+width and Y+height
- •Captures the entire rectangular region containing all monitors
- •Handles coordinate translation automatically
Example: Selecting left and right monitors captures all three monitors in between
Selecting Monitors
There are several ways to specify which monitor(s) to use for automation:
Visual Selection (Runner UI)
RecommendedUse the monitor selector in the Runner interface:
- •Click on individual monitors to select/deselect
- •Select multiple monitors for multi-monitor automation
- •Use the 'All' button to select all monitors
- •The interface shows monitor position, resolution, and primary status
By Position (MCP/API)
Reference monitors by their spatial position:
- •'left' - Leftmost monitor in your setup
- •'right' - Rightmost monitor
- •'middle' - Center monitor (in 3+ monitor setups)
- •'primary' - Your primary display
monitors: ['left', 'right'] // Automate across left and right displaysBy Index (MCP/API)
Reference monitors by their numerical index:
- •Monitor 0 - First detected monitor
- •Monitor 1 - Second detected monitor
- •Monitor 2 - Third detected monitor (if present)
- •Indices are stable across sessions
monitors: ['0', '2'] // Automate on monitors 0 and 2Configuration Examples
MCP Tool - Single Monitor
Run a workflow on a specific monitor using the MCP tool:
mcp__qontinui__run_workflow(
workflow_name="My Workflow",
monitors=["left"]
)MCP Tool - Multiple Monitors
Run a workflow across multiple monitors:
mcp__qontinui__run_workflow(
workflow_name="Multi-Screen Workflow",
monitors=["left", "right"]
)HTTP API - Monitor Indices
Use the HTTP API with monitor indices:
POST http://localhost:9876/run-workflow
{
"workflow_name": "Trading Dashboard",
"monitor_indices": [0, 1, 2]
}List Available Monitors
Query available monitors via MCP:
mcp__qontinui__list_monitors()
// Returns:
{
"count": 3,
"monitors": [
{
"index": 0,
"position": "left",
"width": 1920,
"height": 1080,
"is_primary": false
},
// ...
]
}Common Use Cases
Trading Dashboards
Monitor multiple trading terminals across displays, executing trades based on signals from different screens.
Multi-Application Workflows
Automate workflows that span multiple applications on different monitors (e.g., email on left, CRM on right).
Development Environments
Automate testing across IDE, browser, and terminal windows spread across monitors.
Data Entry from Reference Material
Read data from a reference document on one monitor while entering it into a system on another.
Best Practices
Consistent Monitor Arrangement
Keep your physical monitor arrangement stable. Qontinui Runner relies on monitor positions, so moving monitors may require updating workflows.
Test Single Monitor First
When developing multi-monitor workflows, test on a single monitor first to ensure basic automation logic works before adding complexity.
Use Position Labels for Portability
Prefer 'left', 'right', 'primary' over numeric indices when possible. Position labels are more portable across different setups.
Mind the Gaps
When selecting non-adjacent monitors (e.g., monitors 0 and 2), remember the capture includes the bounding region, which may include monitor 1.
Account for Different Resolutions
If monitors have different resolutions or DPI scaling, test image recognition carefully. You may need to adjust similarity thresholds.
Troubleshooting
Clicks landing on wrong monitor
Solutions:
- •Verify monitor selection includes the target monitor
- •Check that monitor positions haven't changed in OS settings
- •Restart Runner after connecting/disconnecting monitors
- •Test with monitor_indices instead of position labels
Image not found in multi-monitor setup
Solutions:
- •Ensure the monitor containing the image is selected
- •Try selecting all monitors to eliminate selection issues
- •Verify image was captured from the same monitor arrangement
- •Check if DPI scaling differs between monitors
Performance issues with multi-monitor
Solutions:
- •Reduce number of selected monitors to minimum required
- •Use search regions to limit image search area
- •Lower screenshot capture frequency if enabled
- •Consider splitting workflow into monitor-specific segments
Monitor position labels incorrect
Solutions:
- •Check Windows display settings for actual arrangement
- •Use numeric indices as fallback
- •Call list_monitors MCP tool to verify detected positions
- •Primary monitor might not be leftmost - verify physically
Technical Details
Coordinate System Internals
Understanding how Qontinui Runner handles multi-monitor coordinates:
1. Virtual Desktop Origin
The Runner calculates the virtual desktop origin as the minimum X and minimum Y coordinates across all monitors. This is NOT necessarily (0, 0).
// Example: 3 monitors
Left: (-1920, 702) 1920x1080
Primary: (0, 0) 3840x2160
Right: (3840, 702) 1920x1080
Virtual Desktop Origin: (-1920, 0)
Virtual Desktop Size: 7680 x 21602. Screenshot Capture
When finding images, the Runner captures the entire bounding region of selected monitors. Image coordinates are relative to the virtual desktop origin, ensuring clicks land correctly regardless of which monitor contains the target.
3. Coordinate Translation
The Python executor (qontinui library) handles coordinate translation using MSS (multi-monitor screenshot library), ensuring consistency between screenshot capture and mouse positioning.