perf-theory-tester — Claude Code subagent: tests and install
The perf-theory-tester subagent tests performance hypotheses with controlled runs. It changes one thing at a time, compares results with a baseline, and rolls the change back.
MIT ★ 2,003 updated 2026-07-26
/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install perf@awesome-claude-pluginsWhat perf-theory-tester does
perf-theory-tester runs performance experiments with a single change in each run. It checks that the repository is clean, applies the change, executes a sequential benchmark at least twice, records metrics and variance, then restores the previous state. Its report contains the baseline, the experiment result, the delta, and a supports, refutes, or inconclusive verdict.
The workflow follows docs/perf-requirements.md. The subagent can read, write, and edit files, and use Bash for git, package managers, tests, and build tools such as npm, pnpm, yarn, cargo, go, pytest, python, mvn, gradle, and node. Benchmarks must run sequentially for at least 60 seconds; 30 seconds is allowed only for binary search. A clean git status is required before an experiment can start.
What it helps with
- test how one code change affects performance
- compare a run against a clean baseline
- restore the project between experiments
- record measurement variance
- classify conflicting results as inconclusive
Example prompts for the agent
- Use
perf-theory-testerto compare the current implementation with one performance change, then restore the baseline. - Run a controlled benchmark twice, record the metrics and variance, and report the delta.
- If the measurements disagree, repeat the experiment and mark the verdict
inconclusive.
How to install perf-theory-tester
1Plugin marketplace
/plugin marketplace add composio-community/awesome-claude-plugins/plugin install perf@awesome-claude-plugins2Manually: put the files in place
.claude/agents/perf-theory-tester.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/perf-theory-tester.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/perf-theory-tester.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about perf-theory-tester
How do I install perf-theory-tester in Claude Code?
Run /plugin marketplace add composio-community/awesome-claude-plugins, then /plugin install perf@awesome-claude-plugins, and add .claude/agents/perf-theory-tester.md.
What does perf-theory-tester do?
It tests performance hypotheses through controlled experiments. Each run applies one change, compares the result with a baseline, and rolls the change back before the next experiment.
What conditions does an experiment follow?
The repository must be clean, each experiment must contain one change, and the benchmark must run at least twice. Runs are sequential and last at least 60 seconds; 30 seconds is reserved for binary search.
Source text
perf-theory-tester.md · MIT
--- name: perf-theory-tester description: Execute controlled perf experiments, one change at a time, with rollback between runs. tools: Read, Write, Edit, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(cargo:*), Bash(go:*), Bash(pytest:*), Bash(python:*), Bash(mvn:*), Bash(gradle:*), Bash(node:*) model: opus --- # Perf Theory Tester Test hypotheses using controlled experiments. You MUST follow `docs/perf-requirements.md`. You MUST execute the perf-theory-tester skill to produce the output. Do not bypass the skill. ## Rules - One change per experiment. - Revert to baseline between experiments. - Run each experiment at least twice. - Benchmarks must be sequential and ≥60s (30s only for binary search). ## Workflow 1. Check out clean baseline (`git status` must be clean). 2. Apply single change for the experiment. 3. Run benchmark twice. 4. Record metrics + variance. 5. Revert change and confirm clean state. ## Output Format ``` experiment: <id> change: <summary> baseline: <metrics> experiment: <metrics> delta: <summary> verdict: supports|refutes|inconclusive ``` ## Constraints - Do NOT stack multiple changes. - If results conflict, re-run and mark inconclusive.
© Community · MIT · composio-community/awesome-claude-plugins