<path-to-your-agent>” starts the scan.
- Claude Code
- Copilot CLI
- Codex CLI
Type the command with a slash:
/simulate, /simulation-run.Put the plugin name in front:
/plurai-simulation:simulate, /plurai-simulation:simulation-run.Start the command with a dollar sign:
$simulate, $simulation-run.The lifecycle
/simulate runs every stage for you. Each stage is also a command you can run alone, and each one produces what the next one consumes: Scan → Ground (optional) → Build the suite → Run → Fix.
/simulate <path-to-your-agent>
| Command | What it does | What it needs first | What it produces |
|---|---|---|---|
/simulate | Runs the whole flow end to end: scan, ground, build the suite, run, fix plan. It asks up front only what it cannot decide (whether to connect a trace source, whether to remove personal data before uploading, and on a repeat run what this run should do), then keeps one live Report current. | The agent’s path on the first run. Nothing else: the first run signs you in and installs the SDK, after asking. | Everything the five stage commands produce, plus the Report. |
/simulation-scan-agent | Scan. Reads your agent’s code, decides which tools are mocked and which run for real, and shows that as a map for you to approve before it writes any file. | The path to your agent’s code. | The Harness (plurai_sim/simulate.py), plurai_sim/plurai.config.yaml, plurai_sim/simulation_prd.md, and the approved map. |
/analyze-traces | Ground (optional). Exports production traces locally and has the backend turn them into a trace brief, so the mock environment, scenarios and evals match real behavior. By default it then turns the trace failures it found into trace scenarios. | A finished scan. Production traces in LangSmith or Langfuse and their API key, or a saved trace export. | A trace brief on the backend, and trace scenarios under plurai_sim/trace_scenarios/. |
/simulation-generate-suite | Build the suite. Stands up the mock environment, builds a knowledge base when the agent needs one, generates scenarios and evals, and iterates on them until the suite gives sharp signal. | A finished scan. | A deployed mock environment, the final Suite, scenarios.md and evals.md under plurai_sim/artifacts/, and the Report. |
/simulation-run | Run. A simulated user plays each scenario’s persona against your agent on the mock environment, and every eval is scored. It can also record the Run in LangSmith, Langfuse, Arize or Braintrust. | A built Suite. | A scored Run, and optionally an experiment in your observability platform. |
/simulation-fixes | Fix. Finds the root cause of each failing scenario and eval, separates real agent bugs from setup issues, and proposes minimal fixes with evidence. It never edits your agent’s source. When you accept an agent fix, it first records the conversation as a Regression. | A completed Run. | A ranked fix plan in plurai_sim/artifacts/fixes.md, and Regressions for fixes you accept. |
Arguments
You rarely need these. Typed intent works too, for example/simulate rerun the suite.
| Command | Usage |
|---|---|
/simulate | /simulate [agent path] [what this run should do] |
/simulation-scan-agent | /simulation-scan-agent <path-to-agent> [--force] [--component "<name and what it does>"]. --force re-analyzes an agent that already has a saved setup. --component sets up and tests one part of the agent (a sub-agent, tool or subgraph). |
/analyze-traces | --no-trace-scenarios publishes the brief without turning trace failures into scenarios. |
/simulation-generate-suite | /simulation-generate-suite [context] [--no-auto-regressions]. The context is a one-line prompt, a path to a PRD or operating-policy .md file, or --zero-shot. --no-auto-regressions keeps confirmed findings from being recorded as Regressions. |
/simulation-run | /simulation-run [--agent-module-path <path>] [--experiment-name <name>] [--max-concurrent <n>] [--agent-version <v>] |
/simulation-fixes | /simulation-fixes [--run <out-dir>] [--verify]. --verify re-runs the failing scenarios after the fixes. |
Other commands
Use these when you need more control over one part of the suite.| Command | What it does | What it needs first | What it produces |
|---|---|---|---|
/analyze-simulation | Checks the quality of the Suite itself (scenarios, Harness, evals, knowledge base) with an independent reviewer, fixes what belongs to the Suite, and repeats until a review comes back clean. /simulation-generate-suite runs it for you. | A qualification Run of the Suite. | An improved Suite, and a summary of probable agent defects and assumptions to confirm. |
/refine-scenarios | Lets you steer which kinds of scenarios get generated. You describe the scenario families you want, see what changes, refine, then generate. | A finished scan. | A scenario set shaped to your request. |
/build-rag-corpus | Builds a knowledge base for an agent with retrieval or text-to-SQL tools. The SDK extracts the data locally; your data-source credentials never leave your machine. One knowledge base per retrieval tool. | A finished scan, an agent with retrieval or SQL tools, and access to the data source. | A knowledge base on the backend, recorded in plurai_sim/.knowledge_bases. |
/edit-env | Opens a conversation with the backend to change a mock environment or a knowledge base in place: a tool’s return shape, the seeded world state, a wrong fact. A changed mock environment is redeployed. | A mock environment or knowledge base already built. | The edited mock environment or knowledge base. |
/upload-doc-examples | Uploads real example documents (invoices, forms, tickets, reports) so generated documents copy their real formatting. | A finished scan, and an agent that reads, produces or references documents. | An example set on the backend, recorded in plurai_sim/.doc_examples_set_id. |
/ground-scenarios | Grounds scenarios in your real material. It detects whether you have conversations to continue, real records, or both, sends each to the right command, and hands off to scenario generation. | A finished scan, and trace exports or real records. | Grounded scenario bundles, ready for generation. |
/trace-to-scenarios | Turns real conversations exported to disk into scenarios that resume where the real conversation stopped. The conversion is deterministic code, not a model. | A finished scan, thread exports on disk, the raw (not anonymized) posture, and a Harness that can restore a conversation. | Scenario bundles that resume real conversations, then generated scenarios. |
/author-trace-adapter | Teaches the converter a trace format it does not know yet, by writing a reviewed mapping file. It refuses rather than guesses when a record does not map. | A trace export in a format other than LangSmith or LangGraph thread exports. | An adapter at plurai_sim/plurai_adapters/<format>.yaml to commit with your config. |
/upload-scenario-bundle | Publishes folders of real records you choose, so a scenario’s starting data is a real record rather than an invented one. Only the records you select leave your machine. | A finished scan, and one folder per scenario with a record file and a ROLES.md. | A scenario bundle on the backend, recorded in plurai_sim/.scenario_bundle_id. |
/record-regression | Records one confirmed agent issue as a Regression: a folder that replays the conversation that exposed it, so the next suite build keeps a scenario for it. /simulation-fixes runs it when you accept a fix. | A confirmed agent issue from a clean Run. | A folder under plurai_sim/regressions/. |
/optimize-eval | Improves one LLM-judged eval: rewrites its rubric for accuracy or splits it into a cheaper judge, benchmarks the candidates, and adopts one only after you confirm. --revert undoes it. | Generated evals. | An improved eval in plurai_sim/policies_config.yaml. |
/harness-setup | Tells you whether you are signed in to Plurai and signs you in with your browser when you aren’t. Installs the SDK into your agent’s environment when it is missing, after asking. Every other command runs it for you when needed, so you only type it to sign in again, switch organization or check your login. On Codex CLI it also prints hook trust and shell network settings. | Nothing. | Logged in to Plurai., or what still needs doing. |
/plurai-diagnose | Prints a bundle to send to Plurai support. It never includes your token. | Nothing. | A support bundle to paste or attach. |
/plurai-uninstall | Removes what the plugin created in your project and home folder, after you confirm. Then uninstall the plugin itself from your coding agent. | Nothing. | A clean project and home folder. |
To change an eval, a scenario or the mock environment during
/simulate, say what you want in chat. The flow redoes that stage and everything after it.Environments
Saving and switching Environments has no slash command. Say what you want in chat:| Say | What happens |
|---|---|
”save this as env billing-happy” | Saves the current config, scenarios, evals and backend ids under plurai_sim/envs/billing-happy/. |
”switch to env billing-happy” | Makes that Environment active and redeploys its mock environment by id, with no regeneration. |
| ”list envs” | Lists every Environment and its backend status: deployed, sets present, inputs changed since generation. |
Next steps
Configuration
The keys in
plurai.config.yaml.Environment variables
Connect to the backend and set the sandbox.