{"id":48044629,"url":"https://github.com/agent-sh/perf","last_synced_at":"2026-04-04T14:16:55.679Z","repository":{"id":339696625,"uuid":"1163065189","full_name":"agent-sh/perf","owner":"agent-sh","description":"Rigorous performance investigation workflow with baselines, profiling, and evidence-backed decisions","archived":false,"fork":false,"pushed_at":"2026-03-22T23:52:56.000Z","size":1771,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-23T08:42:33.264Z","etag":null,"topics":["ai","automation","benchmarking","code-analysis","devtools","javascript","llm","optimization","performance","profiling"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agent-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T03:29:30.000Z","updated_at":"2026-03-22T23:52:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agent-sh/perf","commit_stats":null,"previous_names":["agent-sh/perf"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agent-sh/perf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sh%2Fperf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sh%2Fperf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sh%2Fperf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sh%2Fperf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agent-sh","download_url":"https://codeload.github.com/agent-sh/perf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sh%2Fperf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","benchmarking","code-analysis","devtools","javascript","llm","optimization","performance","profiling"],"created_at":"2026-04-04T14:16:55.551Z","updated_at":"2026-04-04T14:16:55.660Z","avatar_url":"https://github.com/agent-sh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# perf\n\nStructured performance investigation with baselines, profiling, and evidence-backed decisions - run by AI agents inside your editor.\n\n## Why\n\nPerformance work without structure leads to random micro-optimizations, unmeasured changes, and wasted time. `/perf` enforces a rigorous 10-phase methodology - derived from recorded real investigation sessions - that ensures every optimization is baselined, isolated, measured, and documented.\n\nUse cases:\n\n- Investigating a reported performance regression\n- Establishing baselines before and after a refactor\n- Finding breaking points under load\n- Profiling CPU and memory hotspots with language-native tools\n- Making evidence-backed continue/stop decisions on optimization efforts\n\n## Installation\n\n```bash\nagentsys install perf\n```\n\nRequires [agentsys](https://github.com/agent-sh/agentsys) to be set up in your project.\n\n## Quick Start\n\n```\n/perf --phase setup --scenario \"API response time regression\" --command \"npm run bench\" --version v1.2.0\n```\n\nThis initializes an investigation, records the scenario, and prepares for baselining. The orchestrator walks you through each phase sequentially, checkpointing progress after every step.\n\nTo resume an in-progress investigation:\n\n```\n/perf --resume\n```\n\n## How It Works\n\nEvery investigation follows 10 phases in order. The orchestrator enforces strict rules: sequential benchmarks only, 60-second minimum run durations, one change per experiment, and checkpoint commits after each phase.\n\n1. **Setup** - Confirm the scenario, success criteria, and benchmark command. The benchmark must emit metrics between `PERF_METRICS_START` / `PERF_METRICS_END` markers.\n\n2. **Baseline** - Run the benchmark for 60+ seconds with a 10-second warmup. Results are stored as `baselines/\u003cversion\u003e.json`. This is the reference point for all comparisons.\n\n3. **Breaking point** - Binary search across a parameterized range to find the threshold where performance degrades. Uses 30-second runs (the only exception to the 60-second rule).\n\n4. **Constraints** - Run the benchmark under CPU and memory limits (default: 1 CPU, 1GB RAM). Compare against the unconstrained baseline to identify resource sensitivity.\n\n5. **Hypotheses** - Generate up to 5 hypotheses about the root cause, each backed by evidence from git history and code analysis. No guessing - every hypothesis needs a file path or commit reference.\n\n6. **Code paths** - Use repo-map to identify entry points, hot files, and call chains relevant to the scenario. Narrows the search space before profiling.\n\n7. **Profiling** - Run language-specific profilers: `--cpu-prof` for Node.js, JFR for Java, cProfile for Python, pprof for Go. Capture file:line hotspots and flame graphs.\n\n8. **Optimization** - Apply one change at a time. Validate with 2+ benchmark runs. Revert between experiments to keep the baseline clean.\n\n9. **Decision** - Based on measured improvement, decide whether to continue optimizing or stop. The verdict and rationale are recorded in the investigation log.\n\n10. **Consolidation** - Write the final baseline, close the evidence log, and mark the investigation complete.\n\n## Usage\n\n```bash\n/perf --phase setup --scenario \"startup time\" --command \"node bench.js\" --version v2.0.0\n/perf --resume                                          # continue where you left off\n/perf --resume --phase profiling                        # jump to a specific phase\n/perf --resume --phase baseline --runs 5 --aggregate median\n/perf --resume --phase optimization --change \"replaced O(n^2) loop with hash lookup\"\n/perf --resume --phase decision --verdict continue --rationale \"20% improvement\"\n```\n\n### Key Flags\n\n| Flag | Description |\n|------|-------------|\n| `--resume` | Continue the active investigation |\n| `--phase \u003cname\u003e` | Target a specific phase |\n| `--command \u003ccmd\u003e` | Benchmark command (must emit PERF_METRICS markers) |\n| `--version \u003cver\u003e` | Baseline version label |\n| `--duration \u003csec\u003e` | Override benchmark duration (default 60s) |\n| `--runs \u003cn\u003e` | Number of runs for multi-run benchmarks |\n| `--aggregate \u003cmethod\u003e` | median, mean, min, or max (default median) |\n| `--change \u003csummary\u003e` | Description of the optimization being tested |\n| `--verdict \u003cv\u003e` | continue or stop |\n\n### Investigation Artifacts\n\nState is persisted under `{state-dir}/perf/`: `investigation.json` (active state), `investigations/\u003cid\u003e.md` (evidence log), and `baselines/\u003cversion\u003e.json` (metrics per version).\n\n## Architecture\n\n| Component | Type | Model | Role |\n|-----------|------|-------|------|\n| `perf-orchestrator` | agent | opus | Coordinates all phases, enforces rules |\n| `perf-theory-gatherer` | agent | sonnet | Generates hypotheses from git history and code |\n| `perf-theory-tester` | agent | sonnet | Runs controlled experiments for hypotheses |\n| `perf-analyzer` | agent | sonnet | Synthesizes findings into recommendations |\n| `perf-code-paths` | agent | sonnet | Identifies hot files and entry points |\n| `perf-investigation-logger` | agent | sonnet | Writes structured evidence log entries |\n| `perf-baseline-manager` | skill | - | Baseline storage, one JSON per version |\n| `perf-benchmarker` | skill | - | Sequential benchmark execution |\n| `perf-profiler` | skill | - | Language-specific profiling (CPU, memory, flame graphs) |\n\n## Requirements\n\n- [agentsys](https://github.com/agent-sh/agentsys) runtime\n- A benchmark command that emits `PERF_METRICS_START` / `PERF_METRICS_END` markers\n- Language-specific profiler tools installed for the profiling phase (e.g., Node.js `--cpu-prof`, Java JFR, Python cProfile)\n\n## Related Plugins\n\n- [repo-map](https://github.com/agent-sh/repo-map) - AST-based repository map used during the code-paths phase\n- [git-map](https://github.com/agent-sh/git-map) - Git history analysis for identifying recent changes that may correlate with regressions\n- [enhance](https://github.com/agent-sh/enhance) - Code analysis that can complement perf findings\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-sh%2Fperf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-sh%2Fperf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-sh%2Fperf/lists"}