Your agent on PowerWorldHiveMind.
Confused why it keeps coming back with errors it should have solved itself? Tired of
explaining, again, that SaveCase silently does nothing and that a filtered write
changes nothing at all?
PowerWorldHiveMind juices up your agent. Drop it in, and your assistant stops guessing at PowerWorld and starts knowing it — including the dozen failures that never raise an exception and quietly hand you a wrong answer.
You give it a case. It gives you the analysis. You stop being the documentation.
"Which branches are overloaded" is where most tooling stops. This is built for the work that comes after the readout — the study, not the query:
| Instead of | You get |
|---|---|
| "12 N-1 violations" | "All 12 come from one corridor — the four parallel 69 kV circuits between bus 19 and 23. Losing any one overloads the other three." |
| "here are the loadings" | "Build 19→23 and violations go 12 → 2. Do not build 27→29 — I tested it, and it makes N-1 worse." |
| "the 2024 case has more branches" | "The plan adds 691 branches and 199 generators, retires nothing, and none of it is a renumbering artifact — I checked." |
| "the case has renewables" | "9 of 45 units carry PFW models, so this case can run a weather study. Here is the hourly output." |
It diagnoses, proposes a fix, applies it, and re-verifies — then tells you which options to reject and why. In the remediation demo, two of five plausible reinforcements turned out to make the system worse, including the one an engineer would pick first. That is the difference between reasoning about a network and measuring it.
This repository is a knowledge base — 31 linked markdown files about driving PowerWorld Simulator from Python. There is no software to run. You download it, point your AI assistant at it, and it starts writing PowerWorld code that works instead of code that looks plausible.
Hand it a case file and ask a question in plain English:
"Here's my case at
C:\cases\mysystem.pwb. Which branches are most heavily loaded?""Add a 138 kV line between bus 12 and bus 40 and tell me what it does to the N-1 violations."
If you use Claude Code, Codex CLI, Cursor, or Windsurf, you do not need any of the manual steps below. Paste this whole block into it:
Set this up for me:
1. git clone https://github.com/ChunSikPark/PowerWorldHiveMind.git
2. pip install esapp TeamOverbyeWeather
3. Read PowerWorldHiveMind/AGENTS.md
4. Run the preflight in PowerWorldHiveMind/methods/preflight-powerworld.md and
tell me whether PowerWorld automation works on this machine.
Then you are my PowerWorld expert - I will give you a case file next.
It will do all four steps and report back. Your agent is now juiced.
This does not work in the ChatGPT or Claude websites. They have no access to your
computer: they cannot clone, install, or run anything, and pasting the link only lets
them browse a few pages. For those, use the uploads in dist/ - see
Using it with ChatGPT or the Claude website.
Worked runs on a real 37-bus case — real output, including the failures:
| Demo | What it shows |
|---|---|
| Comparing planning cases | Multi-case. Diff a 2016 vs 2024 case: 691 new branches, 199 new generators, then a contingency set for only the new devices — and the trap that makes the naive answer 87% wrong |
| Violation remediation | The full study. Diagnose 12 N-1 violations down to one cause, test five reinforcements, rank them — and find that two make things worse |
| Adding a device | Three attempts that reported success and created nothing, then the fix. The silent-failure problem in full |
| Power flow & sensitivities | AC, DC, LODF, PTDF — with the 1e8 sentinel and an error whose obvious fix fails the same way |
| Contingency & aux | N-1 from scratch, then auto-generating a filter + contingency .aux |
| Weather to megawatts | PFW models, TimeStep, and why "zero output" is usually a setup bug |
| Handling errors | How the agent recovers on its own, and the three cases where it should stop and ask you |
Just say what you want — the full prompt list:
"Which branches are most heavily loaded?" "Add a line between bus 27 and bus 31 and tell me if it helps N-1." "Run N-1 on everything." "Build me a contingency file for the five most loaded lines." "Run N-1, work out what's wrong, and tell me what to build to fix it." "Compare my 2016 and 2024 cases and tell me what the plan builds."
This section assumes you have never installed Python and have never used an AI coding assistant. If that is not you, skip to Install.
Full walkthrough with screenshots of what you should see at each step: GETTING-STARTED.md
There are four things to get, in this order. Budget about thirty minutes.
Click the green Code button at the top of this page, then Download ZIP. Unzip it somewhere you can find again — your Documents folder is fine.
You do not need git. You do not need an account.
Download it from python.org/downloads and run the installer.
One thing matters: on the first installer screen, tick the box that says "Add Python to PATH" before clicking Install. It is easy to miss and everything downstream breaks without it.
Check it worked — open Command Prompt and type:
python --version
If you see a version number, you are done. If you see "not recognized", the PATH box was not ticked; re-run the installer and choose Modify.
You need one that runs on your computer and can read your files. Pick any:
| Agent | Download | Install command |
|---|---|---|
| Claude Code (best supported here) | claude.com/claude-code | npm install -g @anthropic-ai/claude-code |
| Claude Desktop | claude.ai/download | installer for Mac/Windows |
| Codex CLI (OpenAI) | github.com/openai/codex | npm install -g @openai/codex |
| Cursor | cursor.com | installer |
| Windsurf | windsurf.com | installer |
The npm ones need Node.js first.
Browser chat is not enough. chatgpt.com and
claude.ai in a browser cannot open your .pwb, run Python, or reach
PowerWorld. They can still read this knowledge and write code for you to run yourself —
upload a file from dist/ — but "hand it a case, get an answer" needs one of
the agents above.
Open Command Prompt in the folder where you unzipped this repository, and run:
pip install esapp TeamOverbyeWeather
esapp drives PowerWorld. TeamOverbyeWeather downloads weather data.
Start your AI assistant in the folder where you unzipped this repository — that part matters, since it is how the assistant finds the knowledge. Then ask:
Read AGENTS.md, then run the preflight check to see if PowerWorld works on this machine.
If preflight passes, ask it anything from the table below.
The PowerWorld half of this kit needs three things, and the third one catches people out:
| Requirement | Notes |
|---|---|
| Windows | PowerWorld automation uses a Windows-only interface. No Mac or Linux version exists |
| PowerWorld Simulator, installed and licensed | This kit drives Simulator; it does not replace it |
| The SimAuto add-on, licensed | Licensed separately from Simulator. Your Simulator can work perfectly while automation is unavailable, and the program gives you no hint |
Without a PowerWorld licence, most of this kit is not usable — it is about operating Simulator. The exception is fetching and inspecting weather data, which is pure Python: see methods/teamoverbyeweather-client.md. But applying that weather requires PowerWorld, since TimeStep runs inside Simulator.
For people who already have the tooling.
git clone https://github.com/ChunSikPark/PowerWorldHiveMind.git
cd PowerWorldHiveMind
pip install esapp TeamOverbyeWeatherThen start your agent in that directory. CLAUDE.md and AGENTS.md are picked up
automatically by most assistants.
Claude Code plugin:
/plugin marketplace add ChunSikPark/PowerWorldHiveMind
/plugin install powerworld-hivemind
One-line install (Linux/macOS shell, for the weather half):
curl -fsSL https://raw.githubusercontent.com/ChunSikPark/PowerWorldHiveMind/main/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/ChunSikPark/PowerWorldHiveMind/main/install.ps1 | iexA browser chat cannot open your .pwb, run Python, or reach SimAuto. It can still read
this knowledge and write correct code for you to run yourself, which is most of the
difficulty. Pre-built uploads live in dist/:
| You are using | Upload | Notes |
|---|---|---|
| claude.ai — as a Skill | dist/powerworld-hivemind-skill.zip |
Settings → Capabilities → Skills. Paid plans only |
| claude.ai — as a Project | dist/powerworld-hivemind-bundle.md |
Add to Project knowledge; one file, ~84k tokens |
| ChatGPT — Custom GPT | the three dist/powerworld-hivemind-{methods,concepts,references}.md |
Split to stay under the knowledge-file cap |
| A one-off chat | dist/powerworld-hivemind-bundle.md |
Attach it and ask your question |
Then ask normally. The assistant will hand you code; you run it on the machine that has PowerWorld.
For the full experience — where you hand over a case file and get an answer back — you need an assistant that can read your disk and run code: Claude Code, Codex CLI, Cursor, or Windsurf. See Install.
| Area | Pages |
|---|---|
| Driving PowerWorld from Python | Opening cases, reading and writing data, solving power flow, saving |
| Building and modifying cases | Adding buses, lines, loads and generators; applying a dispatch; reclassifying branches |
| Contingency analysis | Building contingency sets, reading violations, ranking devices by severity |
| Multi-case comparison | Diffing two planning vintages, classifying NEW / RETIRED / UPGRADED / RENUMBERED, and generating contingency sets for just the new devices |
| Violation remediation | Diagnosing the cause, proposing reinforcements or redispatch, applying them, and re-verifying N-1 |
| PowerWorld weather features | The PWW format, and fetching .pww files with the TeamOverbyeWeather client |
| Timestep simulation | Driving PowerWorld's TimeStep feature for hourly renewable output, and reading the result CSVs |
| Script actions | 198 PowerWorld SCRIPT commands, organized by task |
Full catalogue: index.md
Contingency analysis fundamentals, OPF formulation, PV/QV curve studies, and transient stability theory. Nor weather science — dynamic line ratings, IEEE 738 thermal modelling, and extreme-event selection are deliberately out of scope.
This kit is about operating PowerWorld. It will tell you which script action runs a PV study; it will not teach you what a PV curve means.
Most PowerWorld automation problems are not hard, they are quiet. A write to a
filtered subset does nothing and reports success. The COM SaveCase silently no-ops. A
DC solve reports zero mismatch even when the generation schedule is short by a gigawatt.
Contingency results persist stale inside the case file, so a fresh read can be from last
week's run.
None of that is in the vendor documentation, and an AI assistant working from general knowledge will confidently walk into every one of them. These pages are the accumulated list of what actually goes wrong, written so an assistant reads the warning at the exact moment it is about to make the mistake.
Built on esapp (ESA++), the Apache-2.0 PowerWorld
SimAuto wrapper from Texas A&M, and TeamOverbyeWeather.
- A bug in the package → the esapp repository
- A page here that is wrong or missing → open an issue on this repository, and say which page
Page defects are the more valuable report. Every page here exists because someone lost time to the thing it documents.
PowerWorld Simulator is commercial software of PowerWorld Corporation. This is an independent knowledge base and is not affiliated with or endorsed by them.
Read AGENTS.md. It has the traversal protocol, the task-routing table, and the seven rules that fail silently.