gui-test-lease
Skill4 starsChanged 5 months agoMITView on GitHub
Use before running anything that drives or needs the screen, keyboard, mouse, or foreground apps (XCUITest, UI tests, simulator or app automation, computer use, screenshots of real windows), especially when another session or remote peer asked you to run GUI tests on a shared or unattended machine.
In this repository9 other files it gives its agents.
- agent-cprSkill
- anti-sycophancySkill
- cve-remediationSkill
- discord-coordinationSkill
- infisical-proSkill
- microk8s-janitorSkill
- nats-coordinationSkill
- rasp-pi-janitorSkill
- ubuntu-janitorSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 48
Ask the holder via SendMessage(to=<lease.name>): your purpose, how long you need, how urgent.
- Very specific: line 54
If you're the holder and someone asks: yielding between test phases is fine.
- Distinctive: line 67
Delete or edit the lease file by hand.
- Distinctive: line 69
Start GUI work after exit 1 "because it's a quick one".
≈ “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
GUI Test Lease
Overview
A machine has one screen. Two sessions running GUI tests at once steal focus from each other and both runs fail or, worse, pass on garbage. Hold the host-wide lease for the entire time you touch the GUI; nobody else does.
The lease is /tmp/gui-test-lease.json, managed by lease.py next to this
file. It records your pid, session id, peer name (your SendMessage
address), cwd, purpose, who you're testing for, expiry, and a list of waiters.
Commands
L="python3 ~/.claude/skills/gui-test-lease/lease.py", run from your Bash tool
(it reads CLAUDE_PID for identity).
| Step | Command | Exit |
| Check | $L status | 0 |
| Take | $L acquire --purpose "<project>: <what>" --minutes N [--on-behalf-of <peer>] [--wait SECS] | 0 got it, 1 held |
| Extend | $L renew --minutes N (N counted from now) | 0 / 1 not yours |
| Drop | $L release | 0 / 1 not yours |
The run
acquire.--minutescovers the whole run plus margin: you cannot renew while a long foreground test command is blocking you. If a remote peer asked for the test, pass their name as--on-behalf-of. On macOS a successful acquire posts a "GUI TEST" notification so a human at the machine isn't surprised; the project name comes from the<project>:prefix of--purpose, so keep that prefix.- Exit 1: the output names the holder, their purpose,
seconds_left, and you're now recorded inwaiters. Go to Negotiating. - Between test phases,
renew. Its output lists waiters: if someone is queued, send them your honest ETA. releaseas soon as the GUI work ends, whether it passed, failed, or you abandoned it. Do the release before writing up results. The release output lists waiters; message them that the screen is free.
Negotiating
- Ask the holder via
SendMessage(to=<lease.name>): your purpose, how long you need, how urgent. Messages land between their turns, so a holder mid-run won't answer until that command finishes. Don't expect a fast reply. - Short on time?
acquire --wait <secs>polls and takes the lease the moment it frees. Otherwise tell your requester you're queued behind<purpose>, with its expiry, and do non-GUI work meanwhile. - If you're the holder and someone asks: yielding between test phases is
fine.
release, tell them, and re-acquire later. Don't yield mid-run.
Dead leases
acquire reclaims a lease on its own when the holder process is gone, its
registry entry is gone, the pid was reused by another session, or the expiry
passed. The new lease carries reclaimed_from.reason. If the reason is
expiry and that session still exists, message it: it may think it still owns
the screen.
Never
- Delete or edit the lease file by hand. A live, unexpired lease belongs to someone even if they're slow to answer. Negotiate or wait.
- Start GUI work after exit 1 "because it's a quick one".
- Hold the lease across idle time waiting for a human or another peer.
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.

