# Quick Start

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

Set up Shiplight in your coding agent, then create and run your first browser test.

## Step 1: Install Shiplight

Shiplight uses skills to guide your coding agent and an MCP server to give it access to a real browser. Choose your coding agent below, run the command in your terminal, and then restart the agent.

### Choose your coding agent

Each command installs everything the selected agent needs. You can copy and paste it as written.

::: tabs
== Claude Code

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a claude-code -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a claude-code -y
```

== Cursor

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a cursor -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a cursor -y
```

Cursor disables new MCP servers by default. After installation, go to **Cursor → Settings… → Cursor Settings → Tools & MCPs → Installed MCP Servers**, find **shiplight**, and turn it on.

== VS Code

If you use VS Code with the GitHub Copilot extension, run:

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a github-copilot -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a vscode -y
```

== Codex

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a codex -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a codex -y
```

== Gemini CLI

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a gemini-cli -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a gemini-cli -y
```

== Copilot CLI

Install [Copilot CLI](https://github.com/features/copilot/cli) first. You need **Copilot Pro+** and must select **GPT-5.4** or **Claude Opus 4.6** as your model.

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a github-copilot -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a github-copilot-cli -y
```

== Claude Desktop

Claude Desktop does not support Shiplight skills, so install the MCP server only:

```bash
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a claude-desktop -g -y
```

== Zed

Zed does not support Shiplight skills, so install the MCP server only:

```bash
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a zed -y
```

== OpenCode

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a opencode -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a opencode -y
```

== Antigravity

Antigravity stores its MCP settings at the user level, so this command includes `-g`:

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a antigravity -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a antigravity -g -y
```

:::

### Use another coding agent

If your coding agent is not listed above, you can still install the Shiplight skills. Replace `<agent>` with the name used by your agent:

```bash
npx -y skills add ShiplightAI/agent-skills-v2 -a <agent> -y
```

See the [full list of supported agents](https://github.com/vercel-labs/skills#supported-agents) to find the correct name.

### Set up the MCP server manually

If [`add-mcp`](https://www.npmjs.com/package/add-mcp) does not support your agent, add the MCP server to the agent's configuration file yourself. Check your agent's documentation to find the file, then add:

```json
{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"],
      "env": {
        "PWDEBUG": "console"
      }
    }
  }
}
```

### Keep Shiplight up to date

The MCP server uses the latest release automatically. To update the Shiplight skills installed on your computer, run the command that matches how you installed them:

```bash
npx -y skills update -p   # project-level
npx -y skills update -g   # user-level (global)
```

## Step 2: Create your first test

::: tip Use the `/shiplight` command
In your coding agent, type `/shiplight` followed by the task you want to run. For example: `/shiplight verify`, `/shiplight create-yaml-tests`, or `/shiplight fix`. Run `/shiplight help` to see every available command, or `/shiplight help <command>` to learn more about one command. See [Agent-Driven Testing](/local/agent-workflow/#subcommands) for the full list.
:::

### Set up your test project

Open your application's repository in your coding agent, then run `/shiplight init`. Shiplight creates the test structure, installs the required packages, and adds `specs/context.md` for information about your application.

### Set up authentication for the app under test (if needed)

If your application requires users to sign in, run `/shiplight setup-test-auth`. This skill command configures authentication for the **application you are testing** and saves a signed-in browser session so tests can start behind its login screen. It does not create a Shiplight platform API token. See [Authentication](/local/agent-workflow/authentication) for other ways to test signed-in pages.

### Create a test

Tell your coding agent what you want to test. You can use `/shiplight create-yaml-tests` or write the request naturally. Your agent recognizes the request, walks through your application in a real browser, and writes a YAML E2E test that you can read and review.

```
/shiplight create yaml tests for the login flow at localhost:3000
```

### Run the test

Run the following command in your terminal:

```bash
npx shiplight test
```

When the test finishes, open `shiplight-report/index.html`. The report shows whether each step passed or failed, along with screenshots and traces. See [Report](/local/run-locally#report) to change what Shiplight saves.

## Step 3: Fix failing tests

If a test fails after you change your application, run `/shiplight fix`. Your coding agent reproduces the failure, finds the cause, and updates the YAML test when the test is out of date. If the application has a bug, it reports the problem without changing the test. Shiplight handles most outdated element locators automatically while a test runs; see [How self-healing works](/guides/how-self-healing-works).

```
Use /shiplight fix to repair failing tests in ./tests after the latest deployment.
```

For more complex flows, use the local debugger to run the test one step at a time, review screenshots and traces, and edit the YAML yourself. See [Fix a failing test](/guides/fix-a-failing-test) for the complete process.

## Step 4: Run in CI (optional)

You can run the same YAML E2E tests in GitHub Actions, GitLab CI, CircleCI, Jenkins, and other CI services. Read [Where tests run](/local/where-tests-run) to compare your own CI runners with Shiplight-hosted runners, then follow the [CI/CD guide](/local/ci) to set up your workflow.

## Check UI changes as you work

After your coding agent changes the user interface, run `/shiplight verify`. The agent opens your application in a browser and confirms that the change works. You do not need to create a test file first.

```
Update the navbar to include "Pricing" and "Blog" links, then use /shiplight verify to confirm they appear correctly on localhost:3000.
```

## Next steps

- [Guides](/guides/) — Follow step-by-step instructions for common testing tasks.
- [YAML E2E test format](/local/yaml-tests/) — Learn how to read and edit Shiplight test files.
- [Run locally](/local/run-locally) — Run tests on your computer and review the results.
- [CI/CD](/local/ci) — Run your tests automatically with your CI provider.
- [Shiplight Cloud](/cloud_v2/) — Upload results, track flaky tests, and manage CI runners, API tokens, and billing.