shared-machine-checks
Skill0 starsChanged 3 days agoMITView on GitHub
Running heavy checks (test suites, e2e with containers, demos) from many agents on one developer machine without collisions: one shared lock, memory and disk preflight, a compose project and ports per run, cleanup traps, stopping processes by recorded PID, cheap checks before the queue, demos tied to a commit, a waiter for background jobs. Use when more than one agent or worktree runs tests, e2e or containers on the same machine, before starting a heavy check, when a service exits with code 137, when runs collide on ports or on the dev database, when a nohup job ends without a word, or when serving a demo to the person, in any project.
In this repository21 other files it gives its agents.
- adhd-repliesSkill
- assertions-go-redSkill
- clean-codeSkill
- cloud-workerSkill
- context-hygieneSkill
- coordinator-methodSkill
- git-conventionsSkill
- matt-bridgeSkill
- merge-gateSkill
- model-mixSkill
- mod-uiSkill
- overnightSkill
- project-setupSkill
- release-watchSkill
- roadmap-trackerSkill
- screen-mapSkill
- skill-auditSkill
- smart-modsSkill
- smart-ultracodeSkill
- verified-researchSkill
- windows-opsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 10
Every heavy check runs under one lock file shared by all agents and worktrees of the machine, so checks run one at a time.
- Very specific: line 17
Before a check, read the container VM's memory (docker info --format '{{.MemTotal}}') and compare it with what the services need, plus …
- Very specific: line 48
Stop a process only by the PID you recorded or by the tool's own stop command (docker compose down).
- Very specific: line 49
Never pkill -f or killall: a pattern also kills other agents' checks.
- Very specific: line 53
Keep a floor of free disk, for example 15 GB, on the host and in the container VM (df -g /, docker system df).
- Very specific: line 55
Never docker system prune -a --volumes: it removes the developer's dev database volume.
- Very specific: line 59
Before taking the lock run what takes seconds: the commit header lint (git-conventions), conflict markers (git grep -nE '^(<<<<<<<|>>>>>>>) …
- Distinctive: line 80
Every heavy check ran under the shared lock, after the memory and disk preflight.
- Distinctive: line 82
Every process stop used a recorded PID or the tool's own command.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Rules for heavy checks that must run on the developer's own machine, with several agents at work. Where a cloud session or CI can run the check, it goes there first (coordinator-method). The project's scripts and AGENTS.md win over this skill. The merge procedure is merge-gate; models and width are model-mix; the Monitor tool and wakes are overnight.
1. One lock
- Every heavy check runs under one lock file shared by all agents and worktrees of the machine, so checks run one at a time. macOS:
lockf -t <seconds> <file> <command>. Linux:flock -w <seconds> <file> <command>. - A timeout means the machine is busy: report that and wait for a wake. Do not loop on retries.
- Reviewers and coordinators read diffs and logs without the lock. They take it only to run a check.
- The lock path goes in the project's rules file, so every worker uses the same one.
2. Memory preflight
- Before a check, read the container VM's memory (
docker info --format '{{.MemTotal}}') and compare it with what the services need, plus headroom. An identity server such as Keycloak needs about 1.2 GiB alone. A demo that is still running counts too. - Count the heavy containers before starting a check (a 5.9 GiB VM holds three Keycloaks, the checks' own included; a fourth blocks every check). Keep at most one per running worker plus the demo, and stop the dev stack of a parked worktree (
docker compose -p <name> stop, volumes kept) instead of letting checks queue. Why: on 2026-11-13 three workers waited 20+ minutes on memory and one gave up after 53. - A check that stops on low memory is a memory block: free memory, then resume it (the time box does not count the wait,
coordinator-method). - Exit code 137 means the process was killed, here almost always for lack of memory. Name the service and the VM memory in the report. Do not retry blind.
- Restart or resize the VM only between checks and under the lock: it kills every other agent's containers.
- Why: in one run a VM that was too small passed for flaky tests and cost about six hours.
3. Isolation per run
- Each run gets its own compose project name and its own ports, both derived from one number (the PR or the worktree):
COMPOSE_PROJECT_NAME=app-$N,PORT=$((20000 + N * 10)). - A run never touches the developer's long-lived dev database or its ports. It creates its own database and removes it.
4. Cleanup
Install the trap before the first container starts:
cleanup() {
REQUIRED_VAR=dummy docker compose -p "$NAME" down -v --remove-orphans
docker rm -f $(docker ps -aq --filter "label=run=$NAME") 2>/dev/null
docker rmi $(docker images -q "$NAME-*") 2>/dev/null
}
trap cleanup EXIT INT TERMdownfails when a required environment variable is unset, so pass dummy values for each.- Containers started outside the compose project (by test code) carry a
run=$NAMElabel so the trap finds them. - A killed run (SIGKILL) cannot trap. At the next start, sweep its orphans: only processes from this checkout's own venv or
node_modules, found by a recorded PID file or by the checkout's absolute path. Never a broad pattern such asnodeorpython.
5. Stopping processes
- Stop a process only by the PID you recorded or by the tool's own stop command (
docker compose down). Record the PID when you start it. - Never
pkill -forkillall: a pattern also kills other agents' checks. Propose addingBash(pkill *)andBash(killall *)to the permissions deny list; the person changes settings.
6. Disk floor
- Keep a floor of free disk, for example 15 GB, on the host and in the container VM (
df -g /,docker system df). Check it under the lock before a run. - Below the floor:
docker builder prune -ffor the builder cache, then trim the VM disk with the runtime's own tool, under the lock. - Never
docker system prune -a --volumes: it removes the developer's dev database volume.
7. Cheap checks before the queue
Before taking the lock run what takes seconds: the commit header lint (git-conventions), conflict markers (git grep -nE '^(<<<<<<<|>>>>>>>) '), formatting, a fast type check. A 20-minute queue should not end on a typo.
8. A demo for the person
- A demo states which commit it serves:
statusprints the sha and the subject. It switches to another ref only when asked. - Why: the person's click test is worth something only on the commit that will land. Serve the PR head that
merge-gatewill merge, after realigning with main. - The demo has its own project name and ports (section 3).
9. Background jobs
A job started with nohup tells nobody when it ends. Make the job's last log line exit=<code>, then start a separate waiter as its own background task, so its end wakes the agent:
nohup ./check.sh > "$LOG" 2>&1 & echo $! > "$PIDFILE"
while kill -0 "$(cat "$PIDFILE")" 2>/dev/null; do sleep 15; done; tail -n 40 "$LOG"Start long runs in their own session, not plain nohup & as above: a tool shell takes its whole process group with it, and the job dies with no last line. On Linux put setsid before ./check.sh; macOS has no setsid, so use python3 -I -c 'import os,sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])' ./check.sh. The waiter only prints the tail: a tail with no exit= line means the job died, so report it as dead.
Done when
- Every heavy check ran under the shared lock, after the memory and disk preflight.
- Each run used its own project name and ports, and left no containers, images or processes behind.
- Every process stop used a recorded PID or the tool's own command.
- A 137 is named in the report with the service and the VM memory.
- A demo names its commit.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

