PowerWorldHiveMind

Tired of babysitting your coding agent?

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 failures that never raise an exception and quietly hand you a wrong answer.

You give it a case, it gives you the analysis, and you stop having to be the documentation.

Does it work? We measured it: 19 of 23 against 6 for the same assistant with a web browser, marked blind. See the benchmark.

It runs the whole study

Most tooling answers "which branches are overloaded" and stops. The useful work comes after that readout:

It diagnoses, proposes a fix, applies it, re-verifies, and tells you which options to reject. In the remediation demo, two of five plausible reinforcements made the system worse, including the one an engineer would pick first. You only find that out by measuring it.

This repository is a knowledge base: 87 linked markdown files about driving PowerWorld Simulator from Python. The kit itself is markdown, with nothing to build or run. It needs two Python packages, which your agent installs. Point your assistant at it and it starts writing PowerWorld code that works instead of code that looks plausible.

It writes back, too. Say "write that up as a page" and your agent files what you worked out into your own copy, in the same shape as every page here. Your clone does not sync back to this repository, so what you add stays yours. See Add to it.

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."

Install

Paste this into Claude Code. It is a sentence, not a command:

Install the PowerWorld knowledge base: git clone https://github.com/ChunSikPark/PowerWorldHiveMind ~/.claude/skills/powerworld-hivemind

Then load it:

/reload-plugins

That is the whole installation. Anything under ~/.claude/skills/ carrying a .claude-plugin/plugin.json loads automatically, so there is no marketplace to add, no /plugin command, and no terminal. It works in the desktop app and the CLI alike.

Reopening the app is not the same as loading it. Reopening usually restores the same conversation, and a restored conversation keeps whatever it started with. Use /reload-plugins, or start a new conversation.

Then run /powerworld-hivemind:powerworld-setup. That installs the Python packages and checks whether this machine can drive PowerWorld at all, including the separately licensed SimAuto add-on that catches most people.

To update it, ask Claude to git pull in that folder. To remove it, delete the folder.

Codex reads the portable plugin manifest this repo also ships:

codex plugin marketplace add ChunSikPark/PowerWorldHiveMind

Then open /plugins, install powerworld-hivemind, and start a new session. (Not yet tested against a released Codex build — if it fails, clone it by hand and open an issue.)

Any other agent — Cursor, Windsurf, anything that reads your files: clone the repo and start your agent inside the folder.

git clone https://github.com/ChunSikPark/PowerWorldHiveMind
cd PowerWorldHiveMind
pip install esapp TeamOverbyeWeather

Then tell it: Read AGENTS.md and run the preflight.

Never done this before?

The install above assumes Claude Code is already working. From a standing start it is six steps, about fifteen minutes:

1. Install Claude — claude.com/download. Needs a paid plan and Git.
2. Install Python — python.org/downloads, and tick "Add Python to PATH" on the first screen. Missing that box is the most common way this goes wrong.
3. Click Code in Claude, top left. Chat and Cowork cannot see your files.
4. Paste the install line above, then /reload-plugins.
5. Run /powerworld-hivemind:powerworld-setup — it installs the Python packages and checks whether this machine can drive PowerWorld at all.
6. Prove it worked — in a folder unrelated to PowerWorld, ask what pw.esa.SaveCase("out.pwb") does. "Silently writes no file" means it worked. "Saves the case" means the knowledge did not load.

GETTING-STARTED.md is the same six steps with screenshots, what each failure looks like, and what to do about it. Written for someone who has never installed Python or used an AI coding agent.

Which file your agent actually reads

This depends on which route you took, and the two are not the same.

On the plugin route, a plugin ships skills and commands, not instruction files. Claude Code loads skills/powerworld/SKILL.md and skills/knowledge-base-page/SKILL.md, and registers /powerworld-hivemind:powerworld-setup and /powerworld-hivemind:kb-page. It does not load CLAUDE.md or AGENTS.md from the plugin. SKILL.md carries the rules that matter and points at the pages; the routing table in AGENTS.md stays on disk for the agent to open when it needs it.

On the manual route, the instructions live in AGENTS.md, and the kit ships a shim for the tools that load a different filename. There is nothing for you to configure.

Verified against each vendor's own documentation on 2026-09-09 — read off the docs, not smoke-tested on an installed client. GEMINI.md is generated: edit AGENTS.md instead, or your change is overwritten.

Using something not on the list? Find out which filename it loads at startup. If it is not one of the three above, point it at AGENTS.md yourself — and please open an issue, so the next person does not have to work it out twice.

Into an existing project: copy the cloned PowerWorldHiveMind folder in as a subdirectory. The kit is plain markdown — nothing to build, nothing to run.

See it work

Worked runs on a real 37-bus case — real output, including the failures:

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."

Does it actually help?

BENCHMARK.md — the same AI model answered the same 23 PowerWorld questions two ways: with PowerWorldHiveMind on disk, and as a capable assistant told nothing about PowerWorld but free to search the open web. Every answer was then marked right or wrong by a grader that did not know which setup wrote it.

imageWhere PowerWorldHiveMind helps and where it does not

On the things PowerWorld gets wrong quietly, it is not close. 16 questions where Simulator accepts your call, reports success and returns something wrong: HiveMind solved 15. A fresh assistant with the whole open web solved 4. The web can tell you what a command does. It cannot tell you which commands lie about having done it.

On looking up a command name, open PowerWorld's manual instead. HiveMind managed 4 of 7 there and spent more searches doing it than the web did. This repository deliberately does not publish argument syntax, so it will sometimes name the right command and still not give you a signature to call it with.

Overall: 19 of 23 against 6 of 23. The page lists every question, both verdicts, what each setup spent, and how an earlier version of this benchmark was scored wrong.

About PowerWorld itself

The PowerWorld half of this kit needs three things, and the third one catches people out:

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.

Talking to PowerWorld in files instead of function calls

There is a second way to work, and it changes the shape of the conversation rather than the speed of it.

Turn on one setting and Simulator starts watching a folder. Drop a .aux script into that folder and it runs it, then writes the log back out as a text file. That is the entire protocol: write a file, read a file. Nothing of yours talks to PowerWorld.

That is a boundary, not an absence of code. Your agent still writes and runs plenty of it — checking the script before it drops it, watching for the run to finish, and reading the result CSVs — because the log is prose and the answers are in the CSVs. Code on your side, files across the boundary.

Your agent can work this way. It writes the script, you drop it in, and the results come back as CSV files you both read. The useful part is what that does to the working relationship: you see every script before it runs, everything either side produces is a file you can read, diff and archive, and what you are left with at the end is a script you own and can re-run — not a transcript of an API session that happened once.

methods/aux-file-mode.md is the whole thing: the four setup clicks, the rules, and a working template that opens a bus and measures what that did to the system.

It is the slower path, and two costs are worth knowing up front. It is not headless — a dialog has to stay open, so it will not batch or run in parallel. And a script that fails the wrong way is never cleaned up, so Simulator re-runs it every poll interval until you delete the file yourself. Both are on the page, along with the three commands that will silently ruin a run.

Recent builds only — see concepts/version-requirements.md.

What it covers

Full catalogue: index.md

What it does not cover

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.

Why this exists

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.

Add to it

The kit is a knowledge base you are meant to grow, not just read. Anything you work out in a session and leave in the chat is gone when the session ends.

Just say so in plain English. The agent loads the page-writing skill on its own:

write that up as a page save what we just worked out add a page about how the filter expression language handles nested groups document this gotcha before I forget it

Or call it directly:

/powerworld-hivemind:kb-page

The powerworld-hivemind: prefix is part of the name, same as the setup command.

Not using the plugin? Tell your agent to read skills/knowledge-base-page/SKILL.md. It is one self-contained markdown file with no dependencies — nothing to install and no script to run.

What it will do

1. Search first. If a page already covers the topic it edits that page rather than adding a second one. Two pages on one subject is the failure this base exists to avoid.
2. File it in concepts/ (what a thing is), methods/ (how to do a thing), references/ (a code or API surface) or demos/ (a worked run).
3. Write the house shape — frontmatter, then ## Abstract, ## Connections, ## Content, with relative markdown links to related pages.
4. Add the index.md row, so the page is findable. A page nobody can find is a page nobody reads.

Ask it to check the base instead and it runs two one-line checks — which pages have no index.md row, and which links point at a file that does not exist.

Your copy is yours. A clone does not sync back here, so pages you add stay in your repo and nothing you write is published anywhere. If you do want a page upstream, open a pull request.

See it as a graph

Open the repository folder as a vault in Obsidian — Open folder as vault, then Ctrl/Cmd+G — to see the 47 pages and the links between them. Nothing to install or convert. The repo ships .obsidian/graph.json, so the graph arrives coloured by folder with index.md filtered out, since it links to every page and would swamp the view.

Credits and contributing

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.

For agents

Read AGENTS.md. It has the traversal protocol, the task-routing table, and the eight rules that fail silently.