> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plurai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the plugin, sign in, and simulate your first agent with one command.

By the end of this page you will have a test suite for your agent, a full simulation run, and a fix
plan for what broke, all on one live report page.

You need:

* A coding agent: [Claude Code](https://docs.plurai.ai/integrations/claude-code.md), [GitHub Copilot CLI](https://docs.plurai.ai/integrations/copilot-cli.md)
  or [Codex CLI](https://docs.plurai.ai/integrations/codex-cli.md). Cursor support is coming soon.
* An agent written in Python 3.12 or newer, or in TypeScript/JavaScript running on Node. See
  [Agent frameworks](https://docs.plurai.ai/integrations/agent-frameworks.md).
* macOS, Linux or Windows (PowerShell, with Git for Windows and a python.org Python). Agents that need the
  Node bridge aren't supported on Windows.
* `python3` on your `PATH`, for the plugin's own scripts. For a Node agent, Node 22.15 or newer.
* A browser, to sign in to Plurai once.

> [!TIP]
>
> **No agent yet, or want to try it on a toy one first?** Clone a ready-to-run example from
> [500 AI Agents Projects](https://github.com/ashishpatel26/500-AI-Agents-Projects). Its `agents/` folder
> has self-contained LangGraph and CrewAI agents, such as the
> [customer support agent](https://github.com/ashishpatel26/500-AI-Agents-Projects/tree/main/agents/13-customer-support-agent).

There are no credentials to save: the plugin signs you in and installs the SDK for you. On Claude Code and
Copilot CLI there's nothing to set up by hand; Codex CLI needs two settings, covered in its tab below.

## Install the plugin

The plugin installs from the same marketplace on every coding agent. Pick yours:

> [tab] Claude Code
>
> In Claude Code, open your agent's repository and run:
>
> ```bash theme={null}
> /plugin marketplace add plurai-ai/plurai-plugins
> /plugin install plurai-simulation@plurai-plugins
> ```
>
> Choose **project** scope when the install asks, so the plugin loads only in this project and your
> teammates get it too. Restart Claude Code so it loads the plugin's commands.
>
> The first time, Claude Code asks to read the plugin's files outside your project. That's expected. In auto
> mode choose **Yes, and keep allowing any reads outside the working directories**; in default mode choose
> **Yes, allow reading from \<folder> during this session**.

> [tab] GitHub Copilot CLI
>
> In a terminal, run:
>
> ```bash theme={null}
> copilot plugin marketplace add plurai-ai/plurai-plugins
> copilot plugin install plurai-simulation@plurai-plugins
> ```
>
> The skills, hooks and backend tools load with the install. Then start Copilot in your agent's repository
> with the plugin's folder allowed, so it doesn't ask for permission on every plugin file, and with a Claude
> model, since the flows are tuned on Claude:
>
> ```bash theme={null}
> copilot --add-dir <the plugin's folder> --model <a Claude model>
> ```
>
> `/plurai-simulation:harness-setup` prints the plugin's folder. See
> [Install on Copilot CLI](https://docs.plurai.ai/integrations/copilot-cli.md) for the details.

> [tab] Codex CLI
>
> In a terminal, run:
>
> ```bash theme={null}
> codex plugin marketplace add plurai-ai/plurai-plugins
> codex plugin add plurai-simulation@plurai-plugins
> ```
>
> Codex needs two settings the plugin can't make for you:
>
> * **Open the shell's network.** Add this to `~/.codex/config.toml`, or pass
>   `-c sandbox_workspace_write.network_access=true` for one session:
>
>   ```toml theme={null}
>   [sandbox_workspace_write]
>   network_access = true
>   ```
>
> * **Trust the plugin's hooks.** Start Codex in your agent's repository. When it shows **Hooks need
>   review**, choose **Trust all and continue**.
>
> `$harness-setup` prints the exact settings for your install. See
> [Install on Codex CLI](https://docs.plurai.ai/integrations/codex-cli.md) for the details and what network access allows.

## Simulate your agent

Run `simulate` with the file that defines your agent. Only the way you type the command differs:

> [tab] Claude Code
>
> ```bash theme={null}
> /simulate <path-to-your-agent>
> ```

> [tab] GitHub Copilot CLI
>
> ```text theme={null}
> /plurai-simulation:simulate <path-to-your-agent>
> ```
>
> Copilot needs the plugin's name in front of every command. Use the default interactive mode, not
> autopilot: autopilot answers the flow's questions with a canned reply.

> [tab] Codex CLI
>
> ```text theme={null}
> $simulate <path-to-your-agent>
> ```
>
> Codex starts commands with `$`. Use Default mode, not Plan mode. When the flow asks you something, it
> ends the turn: reply in your next message.

You can also just say it: *"Set up Plurai simulation for my agent in `<path-to-your-agent>`."*

### First run: sign in

The first time, `/simulate` sets you up before it starts:

**1. Sign in with your browser**

Your browser opens on the Plurai sign-in page. Sign in, or sign up if you're new, pick your
organization and approve. The plugin saves its own key on your machine: you never see, copy or paste it.
If no browser opens, the chat shows the sign-in link.

**2. Approve the SDK install**

If your project doesn't have the `plurai` SDK yet, the plugin asks once and installs the version it was
tested with into your agent's environment (its venv, conda, poetry or pipenv environment). If it can't find
one, it offers to create `.venv`.

After that, `simulate` and every other Plurai command just run. To sign in again or check who you're signed
in as, run `harness-setup` (`/harness-setup`, `/plurai-simulation:harness-setup` or `$harness-setup`).

### What the flow asks

The flow asks only what it cannot decide for you:

* **Production traces.** Whether to connect a trace source such as LangSmith or Langfuse, or a saved trace export. You can skip this.
  If you want to connect traces later, run `/analyze-traces` or say *"Ground the simulation in our LangSmith
  traces."* See [Ground in production traces](https://docs.plurai.ai/guides/ground-in-production-traces.md).
* **Anonymization on or off.** Whether to anonymize data on your machine before anything is uploaded. See
  [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

Then it runs every stage in order:

**1. Scan**

Reads your agent, maps its flows and tools, and writes `simulate.py` and `plurai.config.yaml`.

**2. Build the suite**

Stands up a mock environment, then generates scenarios and evals for your domain.

**3. Run**

Plays every scenario against your agent, with a simulated user for a conversational agent or a task
input for a task agent. Every eval scores every result.

**4. Fix**

Traces each confirmed gap to the code that causes it and proposes a fix.

Each stage ends with a short summary in chat and updates the same report. On Copilot and Codex the report is
a local file: each summary names its path, and you open it in a browser.

> [!TIP]
>
> You can change anything at any point by saying so in chat, for example *"add a scenario where the
> customer asks for a refund on an expired plan"*. The flow redoes that stage and everything after it.

## Verify

You'll know it's working when your report opens and starts filling in live. `/simulate` opens it as soon as
the flow starts, and each stage fills in its section as it finishes. By the end, **Simulation run results**
and **Gaps and fixes** are filled in. See [Read your report](https://docs.plurai.ai/report/overview.md).

## Troubleshooting

> [accordion] The report didn't open
>
> * **Claude Code:** the page opens in your browser when the run starts, and the chat gives you its private
>   link at the end of the run. Start Claude Code from your agent's folder or a folder above it: from
>   anywhere else, the page stays on your machine and no link is published.
> * **Copilot CLI and Codex CLI:** open `plurai_sim/artifacts/report.html` in your browser and leave it
>   open. It updates by itself.
>
> Still nothing? Check that a `plurai_sim/` folder next to your agent holds `simulate.py` and
> `plurai.config.yaml`. If it doesn't, the scan didn't finish: scroll up in the chat for the reason.

> [accordion] The simulate command doesn't exist
>
> Restart your coding agent after installing the plugin, then check the install:
>
> * **Claude Code:** run `/plugin` and check that `plurai-simulation` is installed and enabled.
> * **Copilot CLI:** run `copilot skill list` and check that there is no "failed to load" section. Type the
>   command with the plugin's name: a bare `/simulate` is an unknown command on Copilot.
> * **Codex CLI:** type the command with `$`, not `/`.

> [accordion] The flow says NOT READY
>
> Every flow checks the install first and prints one line per problem, naming the fix, for example
> `flow-window: NOT READY (hooks): …`. On Codex this usually means the hooks aren't trusted yet (open `/hooks`
> and press `t`) or the shell has no network. See [Codex CLI](https://docs.plurai.ai/integrations/codex-cli.md#run-a-flow) or
> [Copilot CLI](https://docs.plurai.ai/integrations/copilot-cli.md#run-a-flow).

> [accordion] The browser sign-in didn't finish
>
> The command stops with the reason and asks you to run it again. Run the same command again to get a new
> sign-in, or run `/harness-setup` to sign in on its own. If no browser opens, use the link shown in chat.

> [accordion] The flow says the Plurai tools are not connected
>
> This shouldn't normally happen: the plugin picks up your login by itself. If it does, on Claude Code run
> `/mcp reconnect all`; on Copilot or Codex, restart the session. The flow then carries on.

> [accordion] The flow asks to install the SDK
>
> That's expected the first time in a project. Say yes, and the plugin installs the SDK version it was tested
> with into your agent's environment. It needs Python 3.12 or newer. See [Install the SDK](https://docs.plurai.ai/sdk/install.md).

> [accordion] Something else
>
> See the full [Troubleshooting](https://docs.plurai.ai/troubleshooting.md) guide.

> [card] [Stuck? Ask us on Discord](https://discord.gg/bg34gh76uJ)
>
> Get help from the Plurai team and other agent builders in our community, or email
> [support@plurai.ai](mailto:support@plurai.ai).

## Next steps

> [card] [Read your report](https://docs.plurai.ai/report/overview.md)
>
> What each section of the report shows and how to read it.

> [card] [How it works](https://docs.plurai.ai/how-it-works.md)
>
> What each stage does and what it produces.

> [card] [Ground in production traces](https://docs.plurai.ai/guides/ground-in-production-traces.md)
>
> Base scenarios and evals on real conversations.

> [card] [Save an environment](https://docs.plurai.ai/guides/environments.md)
>
> Snapshot your suite and switch between several.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.