> ## 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.

# Install on Claude Code

> Install the Plurai Simulation plugin in Claude Code, sign in, and keep it up to date.

Claude Code is the primary home of the plugin. After this page you have the plugin installed, signed in to
Plurai, and ready to run `/simulate`.

## Requirements

* Claude Code on macOS, Linux or Windows (PowerShell, with Git for Windows and a python.org Python).
* A browser, to sign in to Plurai once.
* `python3` on your `PATH`, for the plugin's own scripts.
* Python 3.12 or newer for your agent's environment. The plugin installs the `plurai` SDK there for you.
* Node 22.15 or newer, if your agent is written in Node. See [Node agents](https://docs.plurai.ai/integrations/node-agents.md).

Start `claude` from your agent's folder or a folder above it. From anywhere else, the report stays on your machine and you won't get a private link.

## Install

**1. Add the marketplace and install the plugin**

In a Claude Code session, run:

```bash theme={null}
/plugin marketplace add plurai-ai/plurai-plugins
/plugin install plurai-simulation@plurai-plugins
```

Install it at **project** scope. The install is then recorded in the project's `.claude/settings.json`, so
teammates get the same plugin, and its commands don't load in projects that never use them. From your shell:

```bash theme={null}
claude plugin install plurai-simulation@plurai-plugins --scope project
```

**2. Restart Claude Code**

Claude Code reads the plugin's skills, hooks and MCP server once, at session start. Exit (`/exit`) and start
`claude` again.

**3. Run your first flow**

```bash theme={null}
/simulate <path-to-your-agent>
```

The first Plurai command signs you in. Your browser opens on the Plurai sign-in page: sign in or sign up,
pick your organization and approve. The SDK creates its own key and saves it on your machine; it is never
shown, typed or copied. If the SDK is missing, the plugin asks once and installs it.

## Sign in again or check your login

Run `/harness-setup`. It tells you whether you're signed in, and signs you in when you aren't. A saved login whose
key has expired counts as signed out, so the next command signs you in again.

To sign out from a terminal, run `plurai logout` in your agent's environment. It revokes the key and removes it from
your machine.

## First run: a read permission prompt

The plugin is installed outside your project, so the first time a command reads the plugin's own reference files,
Claude Code asks *"Read outside the working directories … Allow this read?"*. That's expected:

* **Auto mode:** answer **Yes, and keep allowing any reads outside the working directories**. It won't ask again.
* **Default mode:** answer `Yes, allow reading from <folder> during this session`. It asks once per skill in each session.

For unattended runs, see [Run in CI](https://docs.plurai.ai/guides/ci.md).

## A machine without a browser

1. Create a key under **API keys** in the [web app](https://simulation.plurai.ai). Plurai gives you the backend address with your account.

2. Save the key from a terminal of your own. It asks for the key with echo off and saves it privately in `~/.plurai/credentials.json`:

   ```bash theme={null}
   python3 ~/.claude/plugins/cache/plurai-plugins/plurai-simulation/<version>/scripts/plurai_login.py --url <backend url>
   ```

3. Claude Code reads the backend address from its launch environment, so export it there too and restart Claude Code:

   ```bash theme={null}
   export PLURAI_URL=<backend url>
   claude
   ```

For CI, export `PLURAI_URL` and `PLURAI_TOKEN` instead. See [Environment variables](https://docs.plurai.ai/reference/environment-variables.md).

## Update the plugin

Update the plugin from the `/plugin` menu, or from your shell:

```bash theme={null}
claude plugin update plurai-simulation
```

Then restart Claude Code, because skills, hooks and the MCP server are read at session start. The plugin tells you
once a day when a newer release is out; it never blocks you.

When a new plugin release needs a newer SDK, the plugin stops before a run and prints the install line. See
[Install the SDK](https://docs.plurai.ai/sdk/install.md#upgrade).

## For admins: managed settings

If your organization manages Claude Code settings, two of them decide whether the plugin works:

* **`allowManagedHooksOnly`:** enable the plugin in your managed settings (`"enabledPlugins": {"plurai-simulation@<marketplace>": true}`, with its marketplace under `extraKnownMarketplaces`). Otherwise it runs in a limited mode with some automatic checks off.
* **`allowManagedMcpServersOnly`:** admit Plurai's server by URL in `allowedMcpServers`: `{"serverUrl": "https://*.plurai.ai/*"}` and `{"serverUrl": "https://*.plurai.uk/*"}`. A `serverName` entry can't admit it.

## Uninstall

Run `/plurai-uninstall` to remove what the plugin created in your project and home folder, then remove the plugin:

```bash theme={null}
claude plugin uninstall plurai-simulation@plurai-plugins
```

Add `--scope project` if you installed it for a project. The SDK stays in your agent's environment; remove it with
`pip uninstall plurai-simulation-sdk plurai-mockenv` if you no longer need it.

## Auto permission mode

The plugin's flows run under Claude Code's auto mode without extra configuration. If the permission
classifier ever blocks one of the plugin's scripts, add an `autoMode.allow` entry. See
[Permissions](https://docs.plurai.ai/reference/permissions.md).

## Next steps

> [card] [Quickstart](https://docs.plurai.ai/quickstart.md)
>
> Simulate your first agent.

> [card] [Scan your agent](https://docs.plurai.ai/guides/scan-your-agent.md)
>
> The first stage, in detail.


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