Measure, root-cause, fix, verify and record performance contention on a developer machine: cloud-sync daemons (iCloud Drive, OneDrive, Dropbox, Google Drive), file indexers, AI-tool MCP server fleets, and automation browsers left behind by tests and browser skills. Trigger when the machine is slow, apps freeze, browser or MCP tool calls time out, load exceeds the core count, or before and after any UI/UX/performance test run. Includes the L0–L4 optimisation scale and the test-hygiene contract.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
Agentic delivery runs many things at once on one laptop: several AI CLI sessions, each with its own MCP servers; browser automation (Playwright, Selenium, Puppeteer, a CDP harness); indexers; cloud-sync clients; dev servers; test suites. When they contend, the symptoms look like product bugs — timeouts, flaky UI tests, "the site is slow" — and the next agent spends its budget diagnosing a healthy remote. This skill makes the machine's state a measured input, gives each signature a cause and a bounded action, and makes cleanup a contract rather than a hope.
Script: scripts/perf-guardrail.sh (bash 3.2, macOS, no sudo, no third-party tools). Read-only
except cleanup --yes (kills), icloud throttle|restore (signals) and record (appends). Linux notes are at the end.
| Phase | Command | Output |
|---|---|---|
| 1 Measure | perf-guardrail.sh snapshot --save /tmp/pre.snap, hangs 7, fleet, orphans (rows gives the same as machine-readable lines for CI gates) | load vs cores, memory, swap, top consumers with the session that owns them, sync daemons (a stopped one is flagged), indexer, MCP fleets, automation browsers, and every app hang report with the frames that explain it |
| 2 Attribute | the signature table below | one cause per signature, never "the Mac is slow" |
| 3 Act | only the sanctioned actions below | bounded, reversible, one attempt |
| 4 Verify | perf-guardrail.sh verify /tmp/pre.snap, hangs 1 | a before → after table in the reply; a fix without numbers did not happen |
| 5 Record | perf-guardrail.sh record "<one line>" | a dated lessons file the next agent reads before re-deriving anything |
Interpretation rules: load average on macOS counts runnable threads only, so high load with free
memory is CPU contention, not paging; ps %cpu is a lifetime average, confirm live with
top -l 2 -s 1 -pid; a frozen app (a hang report) is almost never memory — read the report.
| Signature | Cause | Action |
|---|---|---|
Hang reports whose main thread waits in the cloud-sync client (ubiquityIdentityToken → CloudDocs → bird on macOS); the sync daemon shows stat T | someone stopped the daemon with SIGSTOP; its IPC port stays open and every caller waits forever | perf-guardrail.sh icloud restore (SIGCONT). Never SIGSTOP a sync daemon: a stopped process is worse than a dead one, because a dead one returns an error and a stopped one returns nothing |
Load far above the core count, memory fine, a dozen npm exec …@latest / npx processes at 60–80% CPU each | an AI CLI run starting its entire MCP server list; @latest re-resolves against the registry on every start | fleet to find the owner; remove servers the run does not use; pin versions; prefer remote (HTTP) MCP servers over per-session stdio processes |
Indexer (mds_stores, Windows Search) at 150–250% CPU, workers respawning | indexing git repositories and node_modules inside a cloud-synced folder | keep repositories outside the sync root; exclude dev trees from the indexer |
git, rsync, mv asleep for minutes at 0% CPU on a synced path | evicted ("online-only") files being materialised; moving a tree out of the sync root downloads all of it first | work outside the sync root; copy out, verify against origin, delete in place — never mv out. Git state read inside a sync root is not trustworthy: the client can rewrite .git from a stale cloud snapshot |
| Sync client at 50–100% CPU with hundreds of item-not-found errors per 30 s | retry storm after a mass deletion inside the sync root | one restart of the client; then let it drain (overnight, if needed); last resort: sign the folder out and back in |
| Browser family memory > 6 GB, or a headless / throwaway-profile browser or WebDriver whose launcher is gone | a test or browser skill opened it and never closed it | perf-guardrail.sh cleanup lists the candidates; cleanup --yes kills them; --all --yes every disposable one after a test run. Only disposable browsers qualify: headless, or a profile under a temp dir / Playwright / Puppeteer / Selenium / harness path (extend with PERF_DISPOSABLE_RE). A browser on a normal profile is never a candidate, even with --remote-debugging-port — that is a developer's DevTools session; PERF_KEEP_RE protects anything else |
| Several AI CLI sessions each holding stdio MCP children | every session starts its own servers | close idle sessions; remote servers where they exist |
Safe, reversible, no permission needed: SIGCONT a stopped daemon; throttle a sync client to
background priority (taskpolicy -b on macOS, renice/ionice on Linux) rather than stopping it;
kill disposable automation browsers and drivers (cleanup --yes; dry run first); remove unused MCP
servers after backing up the config; one killall of a wedged daemon that its supervisor will respawn.
Needs the operator: system extensions, privileged daemons, indexer privacy lists, turning "optimise storage" off (check how many gigabytes would download first).
Never: SIGSTOP a daemon; unload a system-protected service; mv a tree out of a sync root; kill by
name pattern without reading the parent chain; loop a kill.
Use it to say where a machine or a team is, and what the next step costs.
| Level | State | Evidence |
|---|---|---|
| L0 Unmeasured | slowness is folklore; agents retry and blame the remote | no snapshot, no hang-report triage |
| L1 Measured | one snapshot before retrying anything; WARN/CRIT thresholds | snapshot in every degradation report |
| L2 Attributed | every consumer has an owner; hang reports read; signatures named | fleet, orphans, hangs in the record |
| L3 Governed | sanctioned actions only; sync throttled on a schedule, never stopped; repositories outside the sync root; tests close what they open | scheduler in place, cleanup contract in the test strategy, lessons file growing |
| L4 Self-healing | scheduled checks re-apply throttles and heal stray stops; cleanup runs after every automation job; before/after numbers in every report | zero hang reports over a month; no orphaned browsers older than a run |
afterEach/afterAll or try/finally, and closing runs on failure.cleanup lists is a defect filed against the
suite, with the orphans output as evidence.Copy or symlink this directory into each harness's skill root (Claude Code ~/.claude/skills,
Codex ~/.codex/skills, Antigravity ~/.gemini/config/skills). Headless model lanes that cannot
run commands should be given the script's output to reason over.
Replace memory_pressure with /proc/meminfo, sysctl vm.loadavg with /proc/loadavg,
hang reports with journalctl -p err and coredumpctl, taskpolicy -b with
renice 19 + ionice -c3, and the daemon names with the sync client in use.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Google ADK (Agent Development Kit) orchestration patterns — boundaries, agent composition, and tool seams. Trigger when designing or reviewing multi-agent systems built on ADK. Authoritative source: adk.dev.
The English summary is being prepared. Showing the original description.
JP's signature red-team pass — "how would I break this?" Argue against your own approach before proceeding. Trigger on any high-stakes decision, architecture choice, or before marking work complete.
The English summary is being prepared. Showing the original description.
Read-only SRE checkup of any GCP project: deterministic probes of the edge, Cloud Run services, 7-day error logs, Cloud Scheduler, alert policies and uptime checks, Secret Manager and IAM, the data stores and the machine's own scheduled jobs, audited into one fixed status table (LIVE / WARNING / RED / INCONCLUSIVE) with evidence, findings by severity, what could not be checked, and a single OVERALL line delivered as one notification. Parametrised by a per-project manifest, so the same routine runs on every project. Use when the operator says "cloud checkup", "SRE check", "is everything live", "what's healthy / warning / red", "any errors this week", "audit the infra", "weekly checkup", "set up the weekly checkup", before a deploy or demo, or after an incident. Cloud Run first; App Engine and GKE differ only in the serving probes.
The English summary is being prepared. Showing the original description.
Cloud guardrails for any vendor workload — Google Cloud (GCP, Vertex AI, GKE), AWS (IAM, EKS, Bedrock), Azure (Entra ID, Policy, AKS), Alibaba Cloud (RAM, mainland/international residency). Enforces identity least-privilege, mechanical policy, data boundaries, residency, cost caps, network egress and observability, with official-source validation before any claim. Trigger on any cloud infrastructure design, review, Terraform plan, or LLM/agent deployment; the-architect routes here.
The English summary is being prepared. Showing the original description.
LLM and cloud cost awareness — model tiering, token budgets, right-sizing, and when a cheaper model suffices. Trigger before finalising any architecture that calls LLMs, before scaling a workload, or when a cost estimate is needed.
The English summary is being prepared. Showing the original description.
Challenge vision alignment, value, cost, risk and operating ownership at material scope or release decisions.
The English summary is being prepared. Showing the original description.