perf-theory-gatherer — Claude Code subagent: what it does, install
perf-theory-gatherer analyzes git history and metrics to generate performance bottleneck hypotheses. Useful when investigating speed regressions across multiple runtimes.
MIT ★ 2,003 updated 2026-07-26
/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install perf@awesome-claude-pluginsWhat perf-theory-gatherer does
This subagent inspects git history alongside current metrics to detect performance bottlenecks. It runs on the opus model. Instead of inventing loose theories on its own, it collects repo boundaries and scenario details, then hands off the actual evaluation to the perf-theory-gatherer skill.
Tooling access includes file reading via Read and shell execution through Bash. The agent can invoke git, standard Node package managers, Go, Cargo, Python, pytest, Maven, and Gradle. That lets it inspect dependencies or run targeted profiling scripts directly.
Working with this agent requires a repository file at docs/perf-requirements.md. The subagent must read this file before producing output, and missing documentation blocks the run.
What it helps with
- identify root causes of runtime regressions from commit history
- generate performance bottleneck theories before running profiles
- compare git revisions against requirements in
docs/perf-requirements.md
Example prompts for the agent
- Investigate recent commit history and list hypotheses for increased API latency.
- Run perf-theory-gatherer to evaluate where throughput dropped in the last release.
How to install perf-theory-gatherer
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-gatherer.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-gatherer.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-gatherer.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-gatherer
How to install perf-theory-gatherer in Claude Code?
Run /plugin marketplace add composio-community/awesome-claude-plugins, then execute /plugin install perf@awesome-claude-plugins. The agent definition sits at .claude/agents/perf-theory-gatherer.md.
What does perf-theory-gatherer do?
It inspects git logs and execution metrics to build testable theories about performance bottlenecks.
What files are required for perf-theory-gatherer to work?
The agent must inspect docs/perf-requirements.md before generating theories. Without this file, it refuses to produce output.
Source text
perf-theory-gatherer.md · MIT
--- name: perf-theory-gatherer description: Generate top performance hypotheses after reviewing git history and current metrics. tools: Read, Bash(git:*), Bash(node:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(cargo:*), Bash(go:*), Bash(pytest:*), Bash(python:*), Bash(mvn:*), Bash(gradle:*) model: opus --- # Perf Theory Gatherer Generate hypotheses for performance bottlenecks and regressions. You MUST read `docs/perf-requirements.md` before outputting hypotheses. You MUST execute the perf-theory-gatherer skill to produce hypotheses. Do not bypass the skill. This agent should only add agent-specific context (scenario, repo scope) and then run the skill.
© Community · MIT · composio-community/awesome-claude-plugins