The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Isolated Tester listing page.
AI-powered isolated app testing for macOS. Launch any .app on a virtual display, control it with vision-based AI, and verify behavior — without taking over your screen.
This builds from source, installs binaries to ~/.local/bin/, and configures the MCP server in Claude Code automatically. Then grant Screen Recording and Accessibility permissions in System Settings.
Once installed, these slash commands are available in Claude Code:
| Command | Description |
|---|---|
/test-app <path> <objective> | Launch and test a macOS app in an isolated virtual display |
/test-screenshot [session-id] | Capture a screenshot from a running session |
/test-elements [session-id] | Inspect accessibility elements of a running session |
/test-cleanup | Stop all active test sessions |
Ask Claude Code to call the setup_status tool — it reports version, permissions, virtual display availability, and active sessions.
IsolatedTester creates invisible virtual displays using private CoreGraphics APIs, launches your app there, and lets an AI agent (Claude, GPT-4, or Claude Code CLI) drive the UI through a screenshot → reason → act loop. Your physical screen is never touched.
IsolatedTester requires two macOS permissions:
Check status: isolated displays (will prompt if needed)
See docs/openapi.yaml for the full API specification.
Add to ~/.claude/settings.json:
Then in Claude Code:
"Launch Calculator.app, click the 5 button, then +, then 3, then =, and screenshot to verify the result is 8"
Claude Code will use the MCP tools (create_session, click, screenshot, etc.) to execute the test autonomously.
See docs/mcp-tools.md for all available MCP tools.
Create .isolatedtester.yml in your project directory or ~/.isolatedtester.yml:
Keys are resolved in priority order:
--api-key flag or request parameterANTHROPIC_API_KEY or OPENAI_API_KEY).isolatedtester.yml)com.isolatedtester.apikeys)| Variable | Description | Default |
|---|---|---|
IST_PORT | HTTP server port | 7100 |
IST_TOKEN | Bearer token for HTTP auth | (none, auth disabled) |
IST_CORS_ORIGINS | Allowed CORS origins (comma-separated) | http://localhost:*,http://127.0.0.1:* |
IST_RATE_LIMIT | Max requests per second per client | 10 |
IST_RATE_BURST | Rate limit burst size | 100 |
IST_SESSION_IDLE_TIMEOUT | Idle session timeout in seconds | 1800 (30 min) |
IST_SESSION_MAX_AGE | Maximum session age in seconds | 7200 (2 hr) |
IST_LOG_FORMAT | Log format: text or json | text |
IST_ENV | Config profile (loads .isolatedtester.{env}.yml) | (none) |
ANTHROPIC_API_KEY | Anthropic API key | (none) |
OPENAI_API_KEY | OpenAI API key | (none) |
| Component | Location | Purpose |
|---|---|---|
SessionManager | ServerCore/ | Actor managing concurrent test sessions |
TestSession | Kit/Session/ | Orchestrates display + app + input + capture |
AITestAgent | Kit/Agent/ | Vision-based AI test loop |
VirtualDisplayManager | Kit/Display/ | CGVirtualDisplay (private API) wrapper |
InputController | Kit/Input/ | CGEvent-based mouse/keyboard synthesis |
ScreenCapture | Kit/Capture/ | ScreenCaptureKit screenshot capture |
RequestValidator | ServerCore/ | Input validation for all request types |
CircuitBreaker | Kit/Resilience/ | Fault tolerance for AI provider calls |
AXIntrospector | Kit/Accessibility/ | macOS accessibility tree introspection |
RateLimiter | HTTPServer/ | Token bucket rate limiting |
| macOS Version | Status |
|---|---|
| macOS 15 (Sequoia) | Fully supported |
| macOS 14 (Sonoma) | Fully supported |
| macOS 13 (Ventura) | Supported (CGVirtualDisplay may be unavailable) |
| macOS 12 and earlier | Not supported |
See SECURITY.md for the full security policy.
Key points:
127.0.0.1 only (not network-accessible)See PRIVACY.md for the full privacy policy.
Key points:
run_test sends session screenshots to the AI provider you configure, with your API key./uninstall.sh at any timeSee CONTRIBUTING.md for development setup and guidelines.