Repository navigation
Atuin history provider #144
Description
Goal
Optional support for users who already use Atuin. Native history remains the default. Sync/cloud is never required.
Current state (important)
HistoryService already shells out to atuin history list --cmd-only when Atuin is installed, silently preferring it over $HISTFILE. Atuin recording hooks are preserved in the managed zsh (#16).
Research questions
- Turn the implicit behavior into an explicit provider with status and choice (Provider framework and unified provider UX #134). Changing today's default behavior must be deliberate and noted.
- Query richer metadata (cwd, exit, duration, session) from Atuin to power Rich history search and metadata #143 filters.
- Avoid double recording between Native history and Atuin.
- Performance of per-query CLI calls; caching.
- Behavior when Atuin sync is configured: read-only use of local data, with no sync actions from NMSh.
Acceptance criteria
- Findings comment and decision.
- If adopted: an explicit Atuin history provider with detection, status and fallback to Native.
Dependencies / related
Part of #143. Related #16, #9.
Research references
- https://github.com/atuinsh/atuin (MIT, Rust)
Activity
raiseCatError commentedon Sep 30, 2026
Decision: adopt an explicit optional Atuin provider, with NMSh Native as the default, replacing the prior automatic Atuin preference. The user approved this persisted choice/default change. Select it in Config → Command history provider; the shared provider gallery detects installation/version and Status reports the active source/fallback.
The installed Atuin 18.22.0 help and upstream CLI source expose time, cwd, exit, duration, session and UUID via history list --format/--print0. Duration is a largest-unit display value, so imported durations are approximate. Tabs/newlines in commands survive the fixed-prefix field format. Unknown duration stays unknown.
NMSh uses only local history list, with detached execution, cancellation, a 15-second timeout and 128MiB output limit. No sync/start/end/delete operations are invoked; recording remains owned by the existing zsh hooks. NMSh therefore adds no second Atuin recording path. The upstream history-end path may sync according to the user's existing setup; these hooks are preserved, not altered.
CLI data is loaded in the background on startup or provider change and cached in memory, not fetched per keystroke. Search uses the same bounded/cancellable index as Native. Missing, failed or incompatible tools fall back to Native and expose the reason. Synthetic provider tests verify operation argv and fallback without reading private user history. 100k indexed query measurements are in the performance documentation; local real-database CLI latency has not been benchmarked. Source formats remain optional; Native journals provide exact NMSh timing.
#144 stays open under the milestone release policy.
raiseCatError commentedon Sep 30, 2026
Development implementation is reviewable in #236, with cumulative hardening in #240; final acceptance documentation is #241. These are dependent, unmerged PRs on current dev, with no release/version bump.
The complete code head passed 714 local tests, build, typecheck, benchmark types and diff checks, plus Node 22/26 CI. Architecture and limitations describe what is implemented and deferred. One physical-QA checklist covers the relevant keyboard/layout/provider/privacy checks; it has not been performed.
This issue stays open until release. Project status could not be updated because the available token lacks read:project; active branches/PRs provide durable work status.
raiseCatError commentedon Oct 4, 2026
Implemented on the v0.16 branch (PR #303,
feature/v016-platform-portability-agents). Explicit, read-only Atuin history provider with detection, status and Native fallback:src/shell/historyProviders.ts,tests/historyProviders.test.ts. It was part of the integrated build the maintainer physically validated in the earlier v0.16 QA pass; closing with the implementation.