Repository navigation
Optional shell-tool discovery and first-run setup #9
Description
Status (updated at the v0.16 feature freeze)
Implemented on the v0.16 branch (PR #303, #307): /tools browser (Discover / Installed / Configure / Errors, categories, search, install previews with default-No confirmation, shared progress), truthful installed/selected-provider evidence, optional first-run browse/skip, supported Starship configuration (#83/#252), consent-based mise awareness (#253), curated catalog additions and integration/recommendation/environment/legacy distinctions (#306).
Remaining scope (why this stays open):
- A small local-facts-only
Relevant heregroup (shell scripts, Git repositories, JavaScript manifests, Kubernetes manifests) reusing existing safe context facts; it must never scan or execute project files. The catalog already carries declarativerelevantTometadata for it. - Additional package managers beyond Homebrew, and bulk selection.
- Active-hook detection for shell integrations.
Goal
Extend implemented first-run prompt setup with optional shell-tool discovery. Provider selection, Native appearance, composer layout, and /prompt settings are already implemented. Starship remains optional.
First-run flow
- Detect whether zoxide, fzf, and Atuin are installed and whether their zsh integration is active; show truthful status and next steps.
- Offer Recommended, Choose individually, and Skip.
- Explain each integration's changes before acting. Require explicit confirmation immediately before installation or setup modifies the system. Never install or edit shell configuration silently.
- Preserve compatible shell lifecycle hooks; broader real-zsh/plugin interoperability is Safe user zsh config and plugin interoperability #16. Safe completion widgets and fzf-tab remain unresolved in Configured-zsh completion parity and fzf-tab interoperability #52.
Boundaries
- Do not describe zsh-autosuggestions or zsh-syntax-highlighting as required; NMSh provides their UI roles.
- Do not claim native fzf-tab support.
- Keep Starship optional and do not overwrite its configuration.
This issue also owns the curated shell-tool catalog UX, exposed as /tools and from /settings -> Tools. Ordinary shell tools are not plugins.
Tool browser UX
Use a terminal-native, keyboard-first tabbed browser with the shared panel shell from #90:
Tools | Discover | Installed | Configure | Errors
Tabs without backing behavior may be deferred. There is no marketplace tab or third-party plugin marketplace architecture.
- Discover: curated catalog, search/filter, categories, Recommended indicator, installed/missing state, concise description, package-manager/install source, Enter for details, explicit install confirmation, useful multi-select where appropriate, package-manager-aware actions, visible progress/errors, and factual feedback via Reusable long-running task and install progress UI #91.
- Installed: detected tools with ready state and version/source/integration details when safely and cheaply known. Selecting a tool opens details. Show update availability only when factual and safely inexpensive to determine.
- Configure: controls only for actual safe NMSh workflows. Tool configuration center: read/edit supported tool config inside /settings #83 owns the shared configuration architecture; Starship and Powerlevel10k are tracked separately.
- Errors: actionable problems such as missing expected executables, invalid supported configuration, failed setup, or retained installation failure. Calm empty state: "No tool problems detected."
Keep direct commands valid. Search must not change settings or install tools. Never expose or log secret values; treat secret metadata conservatively.
Catalog categories and ordering
- Search & Files
- Git & Development
- Navigation & History
- Data / Structured Text
- Environment & Secrets
- Shell / Workflow
- Containers / Infrastructure
- Project / Language Tooling
Within each category: uninstalled first, alphabetically among uninstalled; installed afterwards, alphabetically among installed.
Conservative recommendations: zoxide, fzf, ripgrep, fd, jq; gh is useful but not required. Atuin, bat, eza, delta, lazygit, yq, direnv, Doppler, pass, stow, tmux, and cloud/Kubernetes tooling remain optional or specialized. Never silently install.
Related: #83 supported configuration, #90 shared panel shell, #91 install/task progress.
Roadmap update: provider install state
This issue remains the home for optional tool discovery and install flows. The provider framework (#134) reuses its detection and install recipes, so provider pickers show installed/missing state and offer install with the same explicit confirmation and progress UI (#91).
Tools that now back planned providers or integrations:
| Tool | Used by |
|---|---|
| Fastfetch (Neofetch, legacy) | #135 Welcome providers |
| Deja | #139 Deja suggestion provider |
| Carapace | #142 External completion sources |
| Atuin | #144 Atuin history provider |
| zoxide | #147 Directory navigation |
| fzf, Television | #145 Picker providers |
| mise | #154 mise integration |
Unchanged rule: NMSh never installs software automatically. Every install needs explicit confirmation immediately before it runs, shows progress, and reports failure factually. Detecting a tool never changes a setting.
Activity
raiseCatError commentedon Sep 23, 2026
Summary
/promptsettings.Verification
npm run build— passednpm run typecheck— passednpm test— passed (199 tests)git diff --check— passedPhysical terminal validation is still required for onboarding navigation, Starship prompt rendering, segment geometry/palette legibility, resize/history behavior, welcome layout, and Ghostty/Terminal.app keyboard/mouse interaction. Use
node --test scripts/slow-tap-fixture.mjsinside NMSh where relevant.Refs #8
Refs #9
Refs #43
Refs #56
Refs #58
raiseCatError commentedon Sep 23, 2026
PR #60 (
c500f88) merged the onboarding presentation correction. Build, typecheck, 200 automated tests, and Node 22/26 CI passed. Physical validation is still required.In Ghostty first, run a fresh setup and
/prompt:Briefly smoke-check Terminal.app and VS Code integrated terminal. Keep this issue open until this is physically checked.
[-]First-run onboarding and appearance configuration[/-][+]Optional shell-tool discovery and first-run setup[/+]raiseCatError commentedon Sep 24, 2026
Moved to v0.4.0. The prompt/provider/layout onboarding is implemented and tracked in v0.3 (#58, #49). This issue covers only optional shell-tool discovery for zoxide, fzf, and Atuin: Install recommended / Choose individually / Skip, per-tool installed/missing/integration state, and explicit confirmation before any installation. zsh-autosuggestions and zsh-syntax-highlighting are not recommended as required plugins, and fzf-tab support is not claimed (#52).
raiseCatError commentedon Sep 24, 2026
Future direction: categorized tool catalog UI
As this onboarding/discovery flow grows beyond the initial zoxide/fzf/Atuin first-run prompt into a fuller
/toolsor/settings → Toolscatalog, avoid a single flat tool list. Categorize, e.g.:Within each category, sort: uninstalled first (alphabetical), then installed (alphabetical).
Future catalog UX to design toward: scrolling, search/filter, installed/missing state, a Recommended marker, Enter for details, explicit "Install X? Yes/No" confirmation (never silent installs), multi-select where useful, package-manager-aware installation, and visible install progress/errors.
Keep the basic/recommended bundle conservative — zoxide, fzf, ripgrep/rg, fd, jq. Specialized tools (gh, Atuin, bat, eza, delta, lazygit, yq, direnv, Doppler, pass, stow, tmux, cloud/Kubernetes tooling, etc.) are optional catalog entries, not part of the default bundle just because they're popular.
This is future catalog-UX direction layered on top of the existing first-run flow described above — no implementation change from this comment.
raiseCatError commentedon Oct 1, 2026
Checkpoint: draft #255, feature/v09-tools-browser at 9f9ce08, stacked above #254 → #183 → #181 → #182 → final v0.8 #251 (2dfbf9c). No merge/release; package remains 0.7.0.
Implemented searchable optional Tools browser, truthful installed/selected-provider evidence, per-install default-No previews/confirmation and shared progress, Settings/palette links, optional first-run browse/skip, and real supported Starship configuration. No tool installation, hook edit or secret-store read occurred. Additional package managers, bulk selection and active-hook setup/detection are deferred.
Verification: focused 20/20, build/typecheck/diff check passed. Local full suite 726/748 after disk exhaustion caused ENOSPC sandbox creation errors and timeouts; not a passing local full-suite claim. Code-head Node 22/26 CI passed: https://github.com/raiseCatError/notMyShell/actions/runs/36855614986 . Final docs-inclusive CI: https://github.com/raiseCatError/notMyShell/actions/runs/36856000116 . No physical QA claimed.
Local disk resource exhaustion triggered the repository checkpoint rule. Current work is pushed; no new issue implementation started. Resume with adequate disk space, fetch the top, check CI and rerun canonical validation, then implement #253 and #153 before final v0.9 acceptance. Durable handoff: docs/development/v0.9.0-checkpoint.md; single additive QA: docs/qa/v0.9.0-physical-qa.md. Milestone remains incomplete and this issue stays open until release.
raiseCatError commentedon Oct 4, 2026
Shipped in v0.17 (PR #309, #313): the
/toolsRelevant here group from safe local facts, typed package-manager plans (Homebrew, APT, DNF, pacman, zypper) with reviewed bulk install, activation state for zoxide/Atuin/fzf from the running shell, exact-command recognition for every curated tool, and TLDR (tealdeer) as a Recommended tool. Closing.