consult-user-mcp
CLAUDE.md39 starsChanged 4 months agoMITView on GitHub
An MCP server that gives an agent a way to actually ask the user something — native dialogs on macOS and Windows, returning structured JSON. The agent blocks until the user answers, snoozes, or cancels. One MCP server, two platform implementations behind a single DialogProvider interface. The two processes on each platform talk through files, not IPC: the Tray App writes settings.json and snooze state, the Dialog CLI reads them on launch. Read the folder's CLAUDE.md before editing inside it.…
- Commits and pushes
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- container/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
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Read the folder's CLAUDE.md before editing inside it.
- Very specific: line 67
Every interactive dialog can also return snoozed, askDifferently, feedbackText, or cancelled.
- Very specific: line 122
Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Very specific: line 123
Run bd prime for detailed command reference and session close protocol
- Very specific: line 124
Use bd remember for persistent knowledge — do NOT use MEMORY.md files
- Very specific: line 132
Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked.
- Very specific: line 133
Minimal: Keep tool instruction files as pointers to bd prime.
- Distinctive: line 134
Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of …
- Distinctive: line 140
File issues for remaining work: - Create beads for anything that needs follow-up
- Distinctive: line 157
Do not commit or push without clear authority from the active profile or the current user request.
- Distinctive: line 158
If a required sync or push is blocked, stop and report the exact command and error.
≈ “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
Consult User MCP
An MCP server that gives an agent a way to actually ask the user something — native dialogs on macOS and Windows, returning structured JSON. The agent blocks until the user answers, snoozes, or cancels.
<vocabulary>
Canonical terms are defined in GLOSSARY.md. Use these names exactly — they are this project's ubiquitous language.
Core: Dialog, Pane, Feedback, Form, Wizard, Snooze, Ask Differently, Skin, Theme, Baseprompt, Provider, Dialog CLI, Tray App.
The same dialog has a different name at each layer (MCP `pick` = CLI `choose` = `SwiftUIChooseDialog`). That is by design — see the Layer Translation table in GLOSSARY.md before renaming anything.
Full glossary: ./GLOSSARY.md
</vocabulary>Architecture map
One MCP server, two platform implementations behind a single DialogProvider interface.
| Folder | What it is |
mcp-server/ | The MCP server. Tool surface, response compaction, provider selection. TypeScript, Bun. |
dialog-cli/ | macOS Dialog CLI. Ephemeral — spawned per dialog, prints JSON, exits. Swift/SwiftUI. |
macos-app/ | macOS Tray App. Persistent. Owns settings, history, updates, install, debug menu. |
dialog-cli-windows/ | Windows Dialog CLI. Mirrors dialog-cli/. .NET/WPF. |
windows-app/ | Windows Tray App. Mirrors macos-app/. .NET/WPF. |
sketch-cli/ | Grid layout editor behind propose_layout. Separate Swift CLI, macOS only. |
test-cases/ | JSON fixtures + screenshot runner. Feeds both the test runner and the debug menu. |
container/ | Headless macOS VM the suites run inside, so they stop taking your screen. |
docs/ | SvelteKit docs site. Owns releases.json, the release source of truth. |
scripts/ | Build, install, release, and validation shell scripts. |
The two processes on each platform talk through files, not IPC: the Tray App writes settings.json and snooze state, the Dialog CLI reads them on launch.
Context boundaries
Read the folder's CLAUDE.md before editing inside it. Each one carries invariants that are expensive to rediscover:
dialog-cli/CLAUDE.md— before touching any dialog, skin, or keyboard behaviourmacos-app/CLAUDE.md— before touching settings, the debug menu, or install/update flowsmcp-server/CLAUDE.md— before touching the tool surface or providersdialog-cli-windows/CLAUDE.md,windows-app/CLAUDE.md— before any Windows worktest-cases/CLAUDE.md— before adding a dialog type or changing a fixturecontainer/CLAUDE.md— before changing how or where the suites rundocs/CLAUDE.md,sketch-cli/CLAUDE.md
Global invariants
- Dialogs are spawned in the container, not on the developer's screen. Anything that opens a real window —
test:visual,test:keyboard, driving the CLI by hand to see a change — belongs incontainer/. A dialog on the host takes the keyboard from whoever is using it and makes the run unreliable for everyone. - Development builds must go through
bun run dev. The installed app at/Applications/Consult User MCP.appruns its own bundled binaries. A bareswift buildcompiles locally and changes nothing about what actually runs. Restart the tray app afterwards. - All dialog types must be considered together. Adding or changing one touches the MCP server, both CLIs, the test fixtures, the test runner, and the debug menu. The full checklist is in
.claude/rules/dialog-parity.md. - Nothing Windows can be built or verified from macOS. See the
windows-buildskill. CHANGELOG.mdis generated fromdocs/src/lib/data/releases.json. Never hand-edit it.- The Baseprompt is versioned independently of the apps, and its content and version bump together. See
.claude/rules/baseprompt.md.
Dialog types
Eight surfaces across four MCP tools: ask (interactive), notify, tweak, propose_layout (macOS only).
| Dialog | ask type | CLI command | Response |
| Confirm | confirm | confirm | answer: bool |
| Single-select | pick | choose | answer: string |
| Multi-select | pick + multi | choose | answer: string[] |
| Text input | text | textInput | answer: string |
| Password input | text + hidden | textInput | answer: string |
| Form | form | questions | answer: Record<id, string | string[]> |
| Notification | — (notify) | notify | fire-and-forget |
| Value tweak | — (tweak) | tweak | answer: Record<id, number> |
Every interactive dialog can also return snoozed, askDifferently, feedbackText, or cancelled. Field-level detail lives in the tool schemas and mcp-server/CLAUDE.md.
Shared inputs: position (left/center/right), project_path, and the env vars MCP_CLIENT_NAME, DIALOG_THEME, DIALOG_SKIN.
Commands
bun run dev # build all + install to /Applications — the dev workflow
bun run build # mcp-server + dialog-cli only, no install
bun run build:bundle # full release bundle from scratch
bun run test:container # the whole suite, in the macOS container — the verdict
bun test # mcp-server tests
bun run test:layout # assert layout: overflow, overlap, text-fit
bun run test:visual # screenshot every test case ⚠ spawns dialogs
bun run test:keyboard # typing-vs-hotkey contract ⚠ spawns dialogs
bun run changelog # regenerate CHANGELOG.md from releases.jsonRun the suites in the container, not on your desktop. container/launch.sh
run — see container/README.md. The two marked ⚠ spawn real dialogs: on a
machine somebody is using they seize the screen and the keyboard for minutes,
and anything that steals focus mid-run corrupts the result. That is not
theoretical — it is how the visual suite spent months photographing one stuck
window and reporting OK.
test:layout is the one that fails a build, and the one you can safely run
anywhere: it renders every state off-screen, so no window appears and nothing
takes the keyboard. It measures the real view tree and the captured bitmap and
reports clipping, overlapping controls and text that does not fit its box.
test:visual photographs dialogs for a human to read; it does not measure
layout.
A green run is not the same as a clean surface: the audit waives states with known open bugs and says so on every run. Read the waiver list before treating a pass as a release signal.
just also has recipes — just --list. Release procedures are in the release-app skill; Windows builds in windows-build.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6cd5cc61 -->Beads Issue Tracker
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete workRules
- Use
bdfor ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists - Run
bd primefor detailed command reference and session close protocol - Use
bd rememberfor persistent knowledge — do NOT use MEMORY.md files
Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- Conservative (default): Use
bdfor task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. - Minimal: Keep tool instruction files as pointers to
bd prime; use the same conservative git policy unless active instructions say otherwise. - Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
- File issues for remaining work - Create beads for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- Handle git/sync by active profile:
# Conservative/minimal/default: report status and proposed commands; wait for approval. git status # Team-maintainer opt-in only, unless current instructions forbid it: git pull --rebase git push git status - Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step
Critical rules:
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->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.

