> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/ai-testing/plugin.md).

# BugBug Plugin

BugBug Plugin is the recommended way to connect an AI coding agent to BugBug. It installs [BugBug MCP](/ai-testing/mcp.md) and [BugBug Skills](/ai-testing/skills.md) together, so the agent has both live BugBug tools and workflow guidance.

{% hint style="info" %}
BugBug MCP access requires a **Pro or higher** BugBug plan. BugBug Skills are available on **all plans**.
{% endhint %}

## First successful setup

Install with the BugBug CLI, then let your AI client authenticate with BugBug. Choose one of the supported clients below. For another Streamable HTTP MCP client, use the manual configuration on the [BugBug MCP page](/ai-testing/mcp.md).

{% stepper %}
{% step %}

### Install for your AI client

{% tabs %}
{% tab title="Claude Code" %}

```bash
npx @bugbug-io/cli plugin --agent=claude
```

{% endtab %}

{% tab title="Codex" %}

```bash
npx @bugbug-io/cli plugin --agent=codex
```

{% endtab %}

{% tab title="Cursor" %}

```bash
npx @bugbug-io/cli plugin --agent=cursor
```

{% endtab %}

{% tab title="GitHub Copilot" %}

```bash
npx @bugbug-io/cli plugin --agent=copilot
```

{% endtab %}

{% tab title="VS Code" %}

```bash
npx @bugbug-io/cli plugin --agent=vscode
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Restart and sign in

Restart the AI client if it does not load the plugin immediately, then complete its MCP OAuth sign-in flow.
{% endstep %}

{% step %}

### Confirm the connection with a read-only request

Ask the agent for a small, safe action in the BugBug project you expect it to access:

{% prompt description="Verify the BugBug connection" icon="plug" defaultExpanded="full" %}

```markdown
Confirm that BugBug is connected. Read my available BugBug projects and list their names only. Do not create, update, run, import, or delete anything. If you cannot authenticate or access a project, tell me exactly what is missing.
```

{% endprompt %}

If the agent can return the expected projects, you are ready to plan, author, review, and debug BugBug tests.
{% endstep %}
{% endstepper %}

## What it provides

* BugBug MCP with 50 tools for reading project data, creating and maintaining test assets, running tests, and examining run evidence.
* 8 predefined prompts for common planning, authoring, debugging, review, refactoring, and reporting workflows.
* 9 BugBug Skills that guide the agent through safe, BugBug-specific workflows.
* Client configuration for the selected AI client.

## Supported AI clients

| Client         | `--agent` value |
| -------------- | --------------- |
| Cursor         | `cursor`        |
| Claude Code    | `claude`        |
| VS Code        | `vscode`        |
| Codex          | `codex`         |
| GitHub Copilot | `copilot`       |

For a Streamable HTTP MCP client not listed here, follow the [manual MCP configuration](/ai-testing/mcp.md). The CLI plugin route remains the recommended setup because it installs both MCP and BugBug Skills.

## Use it safely

Tell the agent what it may change and what evidence it should inspect. For example:

{% prompt description="Diagnose a failed checkout run" icon="bug" defaultExpanded="full" %}

```markdown
In the BugBug project for <application>, inspect the latest failed checkout run <run-id>. This is read-only: inspect the failed-step details, screenshots, logs, and DOM evidence. If the run ID or required access is missing, ask me for it. Return the likely cause, supporting evidence, and the smallest proposed fix; do not modify the test.
```

{% endprompt %}

For more practical prompts, see [How to use AI with BugBug?](/ai-testing/how-to-use-ai-with-bugbug.md).

## Alternatives

Use [BugBug MCP only](/ai-testing/mcp.md#alternative-setup-bugbug-mcp-only) if you only need live BugBug tools. Use [BugBug Skills only](/ai-testing/skills.md#alternative-setup-bugbug-skills-only) if your agent already has a BugBug connection or you only need workflow guidance.

## Troubleshooting

1. Re-run `npx @bugbug-io/cli plugin --agent=<name>` for the selected client.
2. Restart the client after installation if it does not load the plugin immediately.
3. Complete the client’s MCP OAuth sign-in flow and verify that the client can connect to `https://mcp.bugbug.io/mcp`.
4. Confirm that your BugBug plan includes MCP access.

### Related docs

* [How to use AI with BugBug?](/ai-testing/how-to-use-ai-with-bugbug.md)
* [BugBug MCP](/ai-testing/mcp.md)
* [BugBug MCP tools](/ai-testing/mcp/mcp-tools.md)
* [BugBug Skills](/ai-testing/skills.md)

### FAQ

<details>

<summary>What is the BugBug Plugin, and how is it different from BugBug MCP and BugBug Skills?</summary>

BugBug Plugin is the recommended way to connect an AI coding agent to BugBug. It installs BugBug MCP, BugBug Skills, predefined workflow prompts and the appropriate client configuration together. MCP gives the agent live BugBug tools, while Skills teach it how to use those tools safely and effectively.

</details>

<details>

<summary>Which AI coding agents does the BugBug Plugin support?</summary>

BugBug Plugin supports Cursor, Claude Code, VS Code, Codex and GitHub Copilot. Other AI tools that support Streamable HTTP MCP can connect to the BugBug MCP server through manual configuration, although the Plugin is the recommended setup for supported clients.

</details>

<details>

<summary>How do I install the BugBug Plugin?</summary>

Run the BugBug CLI command with the name of your AI client:

`npx @bugbug-io/cli plugin --agent=<agent>`

Replace `<agent>` with `cursor`, `claude`, `vscode`, `codex` or `copilot`. Restart the client if necessary, then complete the BugBug OAuth sign-in process.

</details>

<details>

<summary>How do I verify that the BugBug Plugin is connected correctly?</summary>

Ask the agent to list the names of your available BugBug projects without changing anything. If it returns the expected projects, the MCP connection and authentication are working. If it cannot access them, restart the client, repeat the OAuth flow and confirm that your plan includes MCP access.

</details>

<details>

<summary>Do I need a paid BugBug plan to use the BugBug Plugin?</summary>

BugBug Skills are available on all BugBug plans, but live access to BugBug projects through MCP requires a Pro or higher plan. Because the Plugin installs both components, users on plans without MCP access can use the Skills but cannot perform live project actions through BugBug MCP.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bugbug.io/ai-testing/plugin.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.