feat(cli): user-friendly first-run — hello, doctor, friendlier errors - #31
Merged
Conversation
Contributor
✅ Shadow AI ScanNo Shadow AI findings detected at or above medium risk. |
Contributor
CRUMB Bench Results
Powered by crumb-format — two-stage context compression |
Three additions aimed at first-touch friction. No wire-format change. - `crumb hello`: 30-second walkthrough. Builds a sample task crumb, validates it, copies to clipboard if a tool is available, prints three concrete next steps. Designed for "fresh install → working crumb in clipboard" with zero flags. `--no-clipboard` skips copy. - `crumb doctor`: install diagnostic. Checks Python version, validator presence, clipboard tool, Palace state, Claude Code integration, MCP registration. Always exits 0 (informational), warnings are advisory. - `_FriendlyArgumentParser`: subclasses ArgumentParser to append a one-line pointer to `--help` and `crumb hello` after argparse's terse "the following arguments are required" / "invalid choice" errors. Propagates to all subparsers via `parser_class=`; no per-subcommand wiring needed. Top-level `--help` now leads with `hello` and `doctor` so new users see the walkthrough as the obvious first step. 15 new tests in test_user_friendly.py cover hello validity, doctor output sections, argparse hint firing, and help-text mentions. Tests: 629 passing (was 614). https://claude.ai/code/session_01Ewf1noyQc9gc6DmohyR32z
slavazeph-coder
force-pushed
the
claude/crumb-v1.3-spec-YCqPD
branch
from
May 5, 2026 17:31
fd31ef3 to
24a8d6e
Compare
slavazeph-coder
marked this pull request as ready for review
May 5, 2026 17:31
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 24a8d6e034
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+5528
to
+5530
| elif system == "Linux": | ||
| candidates = ["xclip", "xsel", "wl-copy"] | ||
| else: |
There was a problem hiding this comment.
crumb doctor currently marks clipboard support as OK when only wl-copy is installed, but _copy_to_clipboard() never attempts wl-copy (it only tries xclip/xsel on Linux). On Wayland systems that have wl-copy but not X11 tools, this produces a false positive diagnostic: doctor reports clipboard ready, while crumb hello/crumb handoff still fail to copy. Either add wl-copy support to _copy_to_clipboard() or stop treating it as a valid tool here.
Useful? React with 👍 / 👎.
5 tasks
slavazeph-coder
added a commit
that referenced
this pull request
May 8, 2026
First post-1.0 minor. No wire-format change (stays at v=1.4). Semver-minor: adds Cursor integration (PR #32), three top-level CLI commands (PR #31: hello, doctor, friendlier argparse errors), --dry-run on installers, stale-doc cleanup. CLI_VERSION → 1.1.0. pyproject.toml version → 1.1.0. 673 tests passing. 39/39 examples + fixtures green on Python and Node.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three additions aimed at first-touch friction. No wire-format change. All additive — every existing flag and command keeps working.
This PR stacks cleanly on top of #29 (1.0.0) and #30 (integrations); landing order doesn't matter (different files).
What's new
crumb hello— 30-second walkthroughLands a brand-new install at "I have a working crumb in my clipboard" with zero flags. Builds a sample task crumb, validates it, copies it, prints three concrete next steps.
crumb doctor— install diagnosticReports Python version, validator presence, clipboard tool, Palace state, Claude Code integration, MCP registration. Always exits 0 (informational), warnings are advisory so it can run in CI without flaking.
Friendlier argparse errors
_FriendlyArgumentParsersubclassesArgumentParserand appends a one-line pointer to--helpandcrumb helloafter argparse's terse "the following arguments are required" / "invalid choice" messages. Propagates to every subparser viaparser_class=; no per-subcommand wiring needed.Help text update
Top-level
--helpnow leads withhelloanddoctorso new users see the walkthrough as the obvious first step:--help-alladds them under aSetup:group alongsideinit,hooks,context,pack.Test plan
python3 -m pytest tests/ -q— 629 passing (was 614; +15 intests/test_user_friendly.py)crumb hello --no-clipboardemits a v=1.3 task crumb that round-trips throughparse_crumbcrumb doctorexits 0 with all warnings (informational)crumb validate(no args) shows the friendly hint pointing atcrumb hellocrumb new frogpile(invalid choice) shows the friendly hintcrumbstill shows core help and exits 0Stats
3 files changed, +388 / -3.
cli/crumb.pycmd_hello, +cmd_doctor, +_FriendlyArgumentParser, register subparsers, update--helptexttests/test_user_friendly.pyCHANGELOG.mdOut of scope
install.sh --dry-run— defers to a follow-up on top of feat(integrations): Claude Code + briefs for Cursor/Aider/OpenCode + RELEASING.md #30 (the install.sh file lives there). Same UX-pass arc; lands once feat(integrations): Claude Code + briefs for Cursor/Aider/OpenCode + RELEASING.md #30 merges.Sequencing with #29 and #30
Disjoint files. Any merge order works. Once #29 lands the version bump to 1.0.0,
crumb doctorwill report1.0.0automatically (it readsCLI_VERSION).https://claude.ai/code/session_01Ewf1noyQc9gc6DmohyR32z
Generated by Claude Code