consult-user-mcp / container
CLAUDE.md39 starsChanged 4 months agoMITView on GitHub
A headless macOS VM (tart) that the test suites run inside. README.md is the operating manual; this file is what to know before editing anything here. Run the suites here, not on the host. test:keyboard and test:visual spawn real dialogs — on a desktop somebody is using they take the screen and the keyboard for minutes, and any focus change corrupts the result. test:layout renders off-screen and is safe anywhere, but the container is still where a verdict should come…
- Reads credentials
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- dialog-cli/CLAUDE.mdCLAUDE.md
- dialog-cli-windows/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- macos-app/CLAUDE.mdCLAUDE.md
- mcp-server/CLAUDE.mdCLAUDE.md
- sketch-cli/CLAUDE.mdCLAUDE.md
- test-cases/CLAUDE.mdCLAUDE.md
- windows-app/CLAUDE.mdCLAUDE.md
- beadsSkill
- release-appSkill
- windows-buildSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
--vnc-experimental, never--no-graphics: No framebuffer means the WindowServer maps no windows, makeKeyAndOrderFront no-ops, and … - Distinctive: line 49
Screen Recording is granted by writing TCC.db: Only possible because SIP is off in the cirruslabs base images.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
Container
What this is
A headless macOS VM (tart) that the test suites run inside. README.md is
the operating manual; this file is what to know before editing anything here.
Run the suites here, not on the host. test:keyboard and test:visual
spawn real dialogs — on a desktop somebody is using they take the screen and
the keyboard for minutes, and any focus change corrupts the result.
test:layout renders off-screen and is safe anywhere, but the container is
still where a verdict should come from, because there the display, the OS
build and the font set are fixed.
Mental model
launch.sh host driver. preflight, boot, trigger, collect.
prep.sh guest provisioning. The ONLY thing baked into the VM.
└─ invoke.sh five-line shim it writes: rsync, then exec the repo's guest-run.sh
guest-run.sh the actual pass. Lives here, arrives with the code it tests.
vnc-matrix.sh end-to-end scenarios over VNC, real keystrokes, jq assertions.
out/ artifacts back from the guest (gitignored)Host and guest never share a process. They talk through two folders: repo
(read-only, the working tree) and out (read-write, artifacts and the
control channel — request.env in, run.log and done back).
Important invariants
- Nothing that can change may be baked into the VM.
prep.shwritesinvoke.shand stops. If you add a step to the pass, it goes inguest-run.sh, which is rsynced fresh every run. The moment the guest carries its own copy of the suite, it starts running a different one from the sources under it — that failure is silent and costs hours. --vnc-experimental, never--no-graphics. No framebuffer means the WindowServer maps no windows,makeKeyAndOrderFrontno-ops, and captures come back empty rather than wrong.- The pass runs in
gui/501, not overtart exec.tart exechas no GUI session. Hence the WatchPaths LaunchAgent, and hence settings arriving by file — launchd hands a job no environment. - A run reboots the VM by default. VirtioFS on a long-lived VM serves
stale file content, so the guest can rsync bytes the host replaced minutes
ago.
REUSE=1skips the reboot when you know the tree has not moved. - Both sides fingerprint the sources. A mismatch aborts the run. It is the only thing standing between a stale share and a test result nobody can reproduce.
- Screen Recording is granted by writing TCC.db. Only possible because SIP is off in the cirruslabs base images. If a capture ever fails with "could not create image from window", check the grant before the layout.
Common change patterns
Adding a suite → a block in guest-run.sh guarded by $SUITES, and a
line in the README table. No re-prep.
Adding a guest dependency → prep.sh, then launch.sh prep once.
Debugging a state by hand → launch.sh stop && launch.sh shell boots
with a viewer. The repo is mounted read-only at
/Volumes/My Shared Files/repo; the guest works in ~/work/consult-user-mcp.
A run that hangs → out/run.log is written live; tart exec
tahoe-consult bash -lc 'tail ~/.consult-mcp-runner/agent.log' reaches the
agent's own log when the shared folder is the thing that broke.
Related context
../test-cases/CLAUDE.md— the suites themselves, and what they can see../CLAUDE.md— where the container sits in the projectREADME.md— the operating manual
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.

