Skip to main content
This page takes you from nothing to a running simulation flow on GitHub Copilot CLI. The flows are the same as on Claude Code, but you type the plugin’s name in front of each command: /plurai-simulation:simulate runs everything end to end, and /plurai-simulation:simulation-scan-agent, /plurai-simulation:simulation-generate-suite, /plurai-simulation:simulation-run and /plurai-simulation:simulation-fixes run one stage each. The first Plurai command signs you in through your browser and installs the SDK for you.

​
Requirements

  • macOS, Linux or Windows (PowerShell, with Git for Windows; Python agents only), with python3 on the PATH. Every hook runs as python3 ….
  • GitHub Copilot CLI. Verified on 1.0.91 through 1.0.93; a newer version is unverified until this page lists it. Copilot updates itself unless you set COPILOT_AUTO_UPDATE=false.
  • Python 3.12 or newer for your agent’s environment. The plugin installs the plurai SDK there.
  • A browser, to sign in or sign up. On a machine without one, see No browser.

​
Set up

1

Install the plugin

The skills, hooks and backend MCP server load with the install. There is nothing to approve.
2

Check that every skill loaded

The output has no “failed to load” section when every skill loaded.
3

Start Copilot with the plugin's folder allowed

The plugin installs outside your project, so Copilot asks for path access on each plugin script and reference file it touches. A full /plurai-simulation:simulate run asked 22 times in testing, and an unanswered prompt stalls the run. --allow-all-tools does not cover paths. Allow the folder up front:
/plurai-simulation:harness-setup prints the plugin’s folder. --add-dir also loads that folder’s .github/skills and .github/agents as trusted configuration.
4

Check the install

In a Copilot session, run:
It says whether you are signed in, and signs you in when you are not.
5

Sign in

There is nothing more to run: the first Plurai command signs you in. It opens your browser, where you sign in or sign up, pick your organization and approve. The SDK creates its own key and saves it; the key is never shown, typed or copied. When the SDK is missing, the command asks once and installs it first.The plugin’s backend tools pick up the new login in the same session. If Copilot does not refresh them, the command says Restart Copilot to connect Plurai, then run <command> again.

​
No browser

On a machine without a browser, create a key in the Plurai dashboard and save it once, in a terminal of your own:
It asks for the key with echo off. Run it in your own terminal, never through the model. You can also export PLURAI_URL and PLURAI_TOKEN together in the environment that launches Copilot. See Environment variables.

​
Run a flow

Start Copilot in your agent’s project and type the command with the plugin’s name. simulate runs every stage:
To go one stage at a time, start with /plurai-simulation:simulation-scan-agent <path-to-your-agent>.
  • Use the qualified form. A bare /simulation-scan-agent <path-to-your-agent> is an unknown command on Copilot. A bare command with no arguments goes through Copilot’s picker, which runs the first match on Enter; that can be a different flow.
  • At the keyboard, use the default interactive mode, not autopilot. The flows ask you questions at their gates (grounding, topology approval, run readiness, fix selection), and autopilot answers them with a canned reply. Unattended runs are the exception: they use autopilot, as shown in Headless runs.
  • Choose a Claude model. Copilot routes to a GPT model by default and the skills are tuned on Claude. Pass --model <model>.
  • Keep gated steps in the main agent. A Copilot subagent has its own session, and the plugin’s guards do not follow it there.
  • Set COPILOT_ALLOW_ALL=true only in a directory you trust. That exact value auto-approves every tool and trusts the working directory, which loads its skills, plugins, MCP servers and hooks.
A missing login is not a problem: the flow signs you in and carries on. Every flow checks the rest of the install first and stops with one line per problem:

​
Headless runs

copilot -p cannot ask you anything. Declare that nobody is there with PLURAI_SIM_NONINTERACTIVE=1, or workspace.run_driver: headless in plurai.config.yaml. Each gate then takes its default, or records a finding and stops when only you can supply the answer.
  • Start each stage with -p in autopilot. Create ~/.plurai first, and allow the plugin’s folder and ~/.plurai. /plurai-simulation:harness-setup prints this line with your folders filled in:
  • Run /simulate’s stages one by one. /simulate can’t start under -p, so run each stage in its own -p call.
  • Declare gates with no default before you start. The anonymization posture has no default, so set anonymize: true or false in plurai.config.yaml first.
  • Put the agent’s provider key in the agent’s own .env. Copilot removes provider variables such as OPENAI_API_KEY from the model’s shell. The runner reads the gitignored .env next to the agent module.
  • Sign in once in an interactive session first. A headless run with no login stops with “Plurai is not logged in. Sign in once in an interactive session, then run this again.” In CI, export PLURAI_URL and PLURAI_TOKEN instead.
  • Allow every folder the run reads with --add-dir, the plugin’s folder included.
See Run in CI.

​
Use a non-default backend

A test or self-hosted backend needs its URL exported in the environment that launches Copilot:
With no key exported, the browser login signs in to that backend. The URL must be https, or http to a loopback address. A saved login belongs to one backend; the plugin does not hand its key to another. A backend outside *.plurai.ai and loopback needs PLURAI_URL and PLURAI_TOKEN exported together.
If you run the plugin from a local checkout, do not add a .mcp.json at its root. Copilot loads a root .mcp.json and it hides the MCP servers of every manifest, so the backend tools disappear.

​
What differs from Claude Code

  • Commands carry the plugin’s name: /plurai-simulation:<command>. The hand-off names the next command the same way.
  • There is no autopilot for gated flows.
  • Copilot picks a GPT model unless you pass --model.
  • Subagents run outside the plugin’s session-keyed guards.
  • There is no dropped-turn rescue. A turn that dies on an API error is not re-driven; re-invoke the same command and it resumes.
  • The report is a local file, not a link. Each hand-off names its path; open it in a browser. It refreshes in place while a Run plays.

​
Update

Restart the session afterwards.

​
Privacy

The plugin sends no client-side telemetry. See Data and privacy.

​
Next steps

Scan your agent

The first stage, in detail.

Troubleshooting

Fixes for common setup problems.