Skip to content

copilot-cli-plugin

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

copilot-cli-plugin

README.md

startchaos — Chaos Studio v2 Workspace Plugin

A GitHub Copilot CLI plugin that guides Azure customers through the end-to-end Chaos Studio v2 Workspace experience: provision a workspace, configure scenarios, and execute chaos experiments — all from a single conversation.

Prerequisites

Requirement Minimum Version Notes
PowerShell (pwsh) 7.4+ Cross-platform; winget install Microsoft.PowerShell
Azure CLI (az) 2.75+ winget install Microsoft.AzureCLI. The chaos extension is auto-installed on first use.
GitHub Copilot CLI latest Must support plugin marketplaces
jq (optional) any Fallback to ConvertFrom-Json if absent

Installation

Quickest — install directly from this repo:

copilot plugin install microsoft/chaos-studio:copilot-cli-plugin

Or register the marketplace (so you can discover and update it via copilot plugin):

copilot plugin marketplace add microsoft/chaos-studio
copilot plugin install startchaos@chaos-studio

To pin it in a repo's .copilot-plugins.yaml:

marketplaces:
  - name: chaos-studio
    source: microsoft/chaos-studio

plugins:
  - name: startchaos
    marketplace: chaos-studio

Two ways to use this plugin

Surface Folder For
Skill (interactive) skills/start-chaos Humans driving Chaos Studio from a conversation
MCP server mcp/ Autonomous agents that need typed Chaos Studio tools

Both target Microsoft.Chaos 2026-05-01-preview and use the local az login session for auth.

Skills

Skill Description
start-chaos Orchestrator — auth → workspace → scenario → run
create-workspace Provision workspace + identity + RBAC
setup-scenario Discover, configure, validate scenarios
run-scenario Execute and stream experiment results
chaos-impact Analyze run impact — correlate Azure Monitor signals to targeted resources

MCP tools (for agents)

Install the MCP server. Two install paths:

From PyPI (recommended once published):

pip install chaos-mcp

From source (for development):

pip install -e ./mcp

Register it in your MCP client config (see mcp/mcp-config.example.json):

{ "mcpServers": { "chaos-studio": { "command": "chaos-mcp" } } }

Per-client config snippets (Claude Desktop, Cursor, Codex CLI) are in mcp/README.md. The Copilot CLI plugin wires this up automatically via plugin.json.

Tool Purpose
chaos_create_workspace Provision workspace + identity + Reader RBAC
chaos_get_workspace Fetch workspace
chaos_refresh_recommendations Trigger workspace evaluation
chaos_list_recommended_scenarios List recommended scenarios
chaos_create_scenario_configuration Create/update configuration (LRO-aware)
chaos_validate_scenario_configuration Validate configuration
chaos_fix_resource_permissions Auto-grant scenario target roles
chaos_execute_scenario Kick off a run, return scenarioRunId
chaos_list_scenario_runs Rediscover compact summaries of durable prior runs, with optional configuration/status/resource filters
chaos_get_scenario_run Fetch current state and, after completion, the full durable run report
chaos_cancel_scenario_run Best-effort cancel
monitor_query_metrics Query Azure Monitor metrics for a resource over a time window
monitor_query_logs Run a KQL query against a Log Analytics workspace
monitor_search_activity_log Search the Azure Activity Log for resource events

See mcp/README.md for the full agent integration guide and publishing instructions (PyPI + Smithery).

Continue after the agent session ends

The MCP server does not keep conversational state. Chaos Studio does keep the authoritative run records. A fresh agent session can call chaos_list_scenario_runs, select the relevant run, and then call chaos_get_scenario_run to recover its targets, timing, action results, and errors. This keeps continuity in the service rather than in one model context.

Usage

> /start-chaos

# The orchestrator will guide you through:
#   Phase 0 — Azure CLI authentication
#   Phase 1 — Create a Chaos Studio workspace
#   Phase 2 — Set up a scenario configuration
#   Phase 3 — Run the chaos experiment

Impact Report

After a chaos run completes, use /chaos-impact to automatically correlate Azure Monitor signals (metrics, logs, activity log, alerts, service health) with the targeted resources and classify them as chaos-attributed, baseline, or unexplained.

> /chaos-impact <scenarioRunId>

# Produces:
#   impact-<runId>.md    — Markdown report card (per-action signal tables)
#   impact-<runId>.json  — JSON sidecar (schema v1, suitable for cross-run diffing)

Parameters

Parameter Default Description
<scenarioRunId> (required) The run to analyze
-Buffer PT5M Pre/post window buffer (ISO-8601 duration)
-OutputDir session dir Where to write artifacts
-MaxResources 50 Per-run resource fan-out cap
-LogAnalyticsWorkspaceId (auto-discovered) Override when discovery fails; pass none to skip logs entirely
-Format both markdown, json, or both

Exit codes

Code Meaning
0 Report emitted successfully
1 Hard error (details on stderr / in an error card)
2 Missing run context — re-invoke with the missing parameters
3 Log Analytics workspace not discoverable for ≥ 1 resource — supply -LogAnalyticsWorkspaceId <id> or -LogAnalyticsWorkspaceId none
4 Permission gap — ensure caller has Monitoring Reader on the targeted resource groups

How it works

  1. Pulls the ScenarioRun resource from ARM.
  2. Flattens scenarioRunSummary[*].resources[*].id → unique target set.
  3. Discovers Log Analytics workspaces via diagnostic settings on each resource.
  4. Queries metrics, resource logs (KQL), activity log, alerts, and service health over [run.startedAt − buffer, run.completedAt + buffer].
  5. Classifies each signal by time-overlap, target-overlap, and magnitude vs. baseline.
  6. Renders a Markdown report card and a JSON sidecar.

See docs/impact-synthesis-skill.md for a full walkthrough.

Configuration Overrides

Copy .chaos-plugins.yaml.example to your repo root as .chaos-plugins.yaml and customize polling intervals, timeouts, and defaults.

State File

The plugin persists progress to $env:STARTCHAOS_STATE_PATH (default: ${SESSION_DIR}/startchaos-state.json). Re-invoking the orchestrator resumes from the first incomplete phase.

Sample Transcript

See docs/impact-synthesis-skill.md for a full walkthrough including a sample impact report.

[placeholder — a full happy-path transcript will be added here]

API Version

All ARM calls target 2026-05-01-preview (Microsoft.Chaos namespace).

License

MIT