Driving surge from Claude Code
surge ships as a Claude Code plugin: six skills and two agents that read a codebase, decide what is worth load testing, write the scenario, rehearse it against the real system, run it and read the result back as findings rather than percentiles.
claude plugin marketplace add https://gitlab.com/agentic-fx/surge
claude plugin install surge@surgeAnyone working inside the surge repository already has them: the originals live in .claude/, and plugin/ is a synchronised copy for every other repository.
The skills
| Skill | What it does |
|---|---|
/surge:perf-plan | writes the test plan before the test: which kind of test, what has to be true of the environment and the data, who watches what while it runs, and what gets cleaned up after |
/surge:perf-setup | takes a project with no performance tests and leaves it with tests that run, mean something, and fail for the right reasons |
/surge:perf-run | runs a scenario and reads the result: why it passed or failed, which request broke and what the server replied, and the reasons not to trust the numbers |
/surge:perf-gate | baselines, and a regression gate that survives a noisy runner |
/surge:perf-capacity | searches for the point where the system stops keeping up, and reads the knee honestly |
scenario-reference | the format itself — the YAML, the Go API, the protocols, the commands. Loaded before writing a scenario so the syntax is right the first time |
Two agents come with it: perf-author explores a codebase and drafts a scenario with the correlation worked out, and perf-analyst takes a finished run and the repository and says what broke, with the evidence.
What perf-setup actually does
It is worth knowing, because it is opinionated and the opinions are the useful part.
- Finds what is worth testing — an OpenAPI file, a HAR recording, existing e2e tests, the framework's router, a
.proto, and the WebSocket endpoints none of those list. Then it picks the two or three journeys that carry the business and says which it left out. A load test of fifty endpoints at equal weight measures nothing anyone cares about. - Asks the two things it cannot infer: which environment, and what "fast enough" means. It will not point load at production unless you say so in those words.
- Writes the scenario with the things that matter more than style: one role per kind of user, the login in
on_startand not the flow,mode: per_vuon the accounts feeder, think time, checks that can actually fail, and thresholds — because a run with no thresholds cannot fail, and surge says so in the verdict rather than printing a green word. - Checks it four ways, in order:
validate,preflight,verify, then a small real run. It will not proceed past a failingverify. - Wires it into CI, matching whatever CI the repository already has rather than imposing a new one.
- Says what it built, honestly — which journeys it modelled, which it skipped, where the threshold numbers came from, and what is still guesswork.
Without Claude Code
Nothing here is required. The skills are markdown; they describe what surge does and how to use it, and they are readable on their own in .claude/skills/. Everything they do, you can do with the CLI.