Connect Claude (Desktop & CLI)

TestOwl Desktop includes a built-in Model Context Protocol (MCP) server bridge. When connected, your local Claude AI tools can communicate directly with TestOwl to author tests, analyze DOM snapshots, and execute user journeys.

Key Capabilities

• Zero TestOwl AI Credit Consumption: Test generation and AI Describe queries run directly through your local Claude account, preserving your TestOwl platform credit quota.
• Bi-Directional Tooling: Claude Desktop can generate and author tests inside your TestOwl workspace, while TestOwl can invoke Claude Code for local test analysis.
• Private & Local: All communication between Claude and TestOwl occurs over a secure, owner-only local inter-process channel on your machine.

Prerequisites

1. 1
   TestOwl Desktop App: Installed and running on Windows or macOS.
2. 2
   Eligible Plan: Claude Connect is available on plans with Desktop and AI capabilities.
3. 3
   Claude Installation:
   • Claude Code CLI: Installed (claude in your terminal) and signed in.
   • Claude Desktop: Installed on your computer.

Configuring Claude Connect in TestOwl

Open the TestOwl Desktop App and navigate to Settings → Connect Claude (or open Project Settings → Manage Claude).

1. Connecting Claude Code CLI

The Claude Code CLI card automatically assesses your environment:

• Ready (Green): Claude Code is installed and authenticated.
• Login Required (Yellow): Claude Code is installed but not authenticated. Run claude in your terminal to sign in, then click Check again.
• Not Found: If Claude Code is installed in a non-standard directory, click Change location and enter the path to the executable.
• Connect MCP: Click Connect Claude CLI (MCP). TestOwl automatically registers its local MCP server bridge in ~/.claude.json while safely preserving a .testowl-backup file.

2. Connecting Claude Desktop

1. 1
   In the Claude Desktop card, click Connect Claude Desktop (or Reconnect Claude Desktop if updating).
2. 2
   TestOwl automatically updates your Claude Desktop configuration file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. 3
   Existing custom MCP servers in your configuration are preserved, and an automatic backup (claude_desktop_config.json.testowl-backup) is created.
4. 4
   Restart Claude Desktop to activate the new TestOwl tools.

Using Claude in TestOwl

The "Run with" AI Provider Switch

When authoring tests in the TestOwl dashboard or recorder, look for the Run with switch in the AI panel footer:

• TestOwl AI: Uses TestOwl's managed cloud AI engine and consumes workspace AI credits.
• Claude: Uses your connected local Claude Code / Claude account with zero credit consumption.

Note: If Claude is selected but Claude Code is not running or logged in, TestOwl displays an alert banner with a direct link to Settings → Connect Claude.

Headless and Headful Test Generation

When generating tests with Claude:

• Headless Mode: Claude plans and executes the test in a background browser. It validates each step, performing up to three check runs and two self-healing repairs. Once all steps pass, it hands back an unsaved test case for your review and confirmation.
• Headful Mode: Claude executes inside an active recorder session. You can watch Claude navigate, interact with elements, inspect DOM mutations live, and step in at any point.

Disconnecting Claude

To disconnect Claude at any time:

1. 1
   Go to Settings → Connect Claude in the Desktop App.
2. 2
   Click Disconnect Claude.
3. 3
   TestOwl cleanly removes its server entries from claude_desktop_config.json and ~/.claude.json and closes the local MCP channel.

Next steps