Skip to main content
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.
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:
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:
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

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.

​
A machine without a browser

  1. Create a key under API keys in the web app. 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:
  3. Claude Code reads the backend address from its launch environment, so export it there too and restart Claude Code:
For CI, export PLURAI_URL and PLURAI_TOKEN instead. See Environment variables.

​
Update the plugin

Update the plugin from the /plugin menu, or from your shell:
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.

​
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:
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.

​
Next steps

Quickstart

Simulate your first agent.

Scan your agent

The first stage, in detail.