All notable changes to HintShell will be documented in this file.
- Zero-Flicker Live UI Overlay:
- Eliminate visual flickering during rapid typing by replacing proactive screen clearing with atomic in-place frame overwriting.
- Retain existing overlay frame smoothly until new suggestion results arrive, eliminating blank gap frames.
- Automatically prune trailing lines when transitioning between different suggestion list heights in a single stdout write.
- Fix prompt overlay clearing when deleting the input buffer to empty via Backspace / Delete, ensuring immediate re-triggering upon typing new characters.
- Synchronize atomic overwrite mechanics across both Rust Live PTY and PowerShell PSReadLine overlay modules.
- Apple Intelligence Glow Theme:
- Add
border_color = "apple"with aliasessiri,apple-intelligence,glow, andneon. - Render a smooth 24-bit TrueColor perimeter gradient from Siri cyan and blue through violet, magenta, coral, and amber.
- Use a Siri-blue frosted selected-row background with consistent highlight restoration, preventing background-color artifacts inside matched command text.
- Add
-
Smart Directory Navigation (
cd):- Contextual
cddirectory completion: automatically lists child directories in the current working directory (cwd), sorted by most recent modification time (mtime). - Out-of-the-box shortcut suggestions for
cd ..(parent directory) andcd -(previous directory). - Balanced hierarchy ranking: The highest-scoring historical/frequent command retains the #1 Top Slot, with real-world directory candidates immediately following beneath.
- Contextual
-
Deep Context Engine:
- Automatically identifies project stack markers (
pnpm-lock.yaml,bun.lockb,yarn.lock,Cargo.toml,docker-compose.yml,.git/index) to recommend contextual dev, build, test, and git workflows.
- Automatically identifies project stack markers (
-
Typo Tolerance & Fuzzy Substring Matching:
- Tolerates single-character command typos (Levenshtein distance
$\le 1$ for common slips likegti,dcoker...). - Case-insensitive substring (
contains) fallback matching when exact prefix matches are unavailable.
- Tolerates single-character command typos (Levenshtein distance
-
Customizable UI Config (
~/.hintshell/config.toml):- Automatically generates
~/.hintshell/config.tomlonhintshell initor on first interactive shell launch. - Multi-palette popup border customization (
border_color:apple/siri/glow,rainbow/gemini,purple,blue,cyan,green,yellow,orange,pink,magenta,minimal). - Configurable suggestion count limit (
max_visible) and inline preview toggle (ghost_text).
- Automatically generates
- Git Bash Fast overlay rendering: Fix newline injection and dual-cursor desync in Windows ConPTY by restoring exact relative cursor coordinates via
MoveToand eliminating non-printable control byte leaks fromPROMPT_COMMAND. - Git Bash Fast Tab completion: Synchronize buffer replacement and discard delays so Tab acceptance cleanly stays on a single line without leaving duplicate command artifacts.
- Git Bash startup tracing:
HINTSHELL_TRACE_STARTUPnow enables terminal and file trace output only when explicitly set to1; setting it to0keeps diagnostics disabled. - PowerShell update completion: Keep the active module loaded while
hs updaterestarts and verifies the daemon, preventing a successful npm update from incorrectly reporting missing private daemon helpers.
- Update version check:
hs updatecompares the installed CLI version with npmlatestbefore stopping the daemon or running npm lifecycle scripts, and exits cleanly when the installed version is current.
- PowerShell overlay responsiveness: Remove intentional key-handler delays, bound named-pipe connection and response waits, and cancel predictor IPC when its deadline expires so typing, pasting, and Enter remain responsive.
- Daemon concurrency: Process named-pipe clients independently so a slow client does not delay suggestion requests from other terminal sessions.
- Interactive regression harness: Run manual checkpoints through the real PSReadLine input loop, allowing overlay suggestions and registered key handlers to be tested in a disposable PowerShell session.
- Overlay coverage: Add operator-driven checks for slow and rapid typing, single-line and multiline paste, plus Enter behavior when the daemon is available or offline.
- History retention: The daemon removes only user-recorded commands that have not been used for 90 days and were used fewer than three times. Commands from the default catalog remain protected.
- Manual pruning: Run
hs history prune --dry-runto preview the default 90-day cleanup, or provide--days <N>for an explicit retention period. Run without--dry-runto remove the reported candidates.
- Bounded maintenance: Automatic history cleanup runs during daemon startup at most once every 24 hours, outside the suggestion input path.
- Context cleanup: Pruning removes matching per-directory history records in the same SQLite transaction.
- Git Bash Fast startup: Add an opt-in
hs init --git-bash-fastprofile that starts the live Bash overlay directly through the managed HintShell launcher, uses a minimal isolated rcfile, and keeps the user’s.bashrcand.bash_profileuntouched. - Startup path: Generate a static Bash hook, defer daemon startup away from initial prompt rendering, and record command history asynchronously so the prompt remains responsive.
- ConPTY compatibility: Use stable ASCII internal markers for prompt and working-directory synchronization through Windows ConPTY.
- Bash rcfile loading: Start the live child with
bash --rcfile <managed-file> -i; this avoids the incompatible--norccombination that prevents Bash from loading the requested rcfile. - Bash job notifications: Detach asynchronous command-history writes with
disown, preventing[N]+ Done ...messages from appearing at later prompts.
- Opt-in startup trace:
HINTSHELL_TRACE_STARTUP=1records wrapper, ConPTY, rcfile, and first-prompt timing to~/.hintshell/startup-trace.logwithout relying on terminal output that can be cleared during initialization.
- Windows update progress:
hs updateruns npm lifecycle scripts in the foreground, showing release download and setup output while using bounded npm network retry and timeout settings. - Safe updater shutdown: npm lifecycle cleanup stops only the live
hintshell.exe bashwrapper and daemon, so it does not terminate the CLI process performing the update. - Update efficiency: Remove the redundant
hintshell initafter npm postinstall, reducing the time before the daemon is restarted.
- Installer visibility: Recommend
--foreground-scriptsfor manual installs so users can observe download, extraction, and setup progress.
- Installer lifecycle: Stop both daemon and live wrapper before replacing binaries, use a bounded release download, and extract Windows ZIP archives with PowerShell instead of Git Bash
tar. - Isolated configuration: Support test-specific home, shell-profile, and data paths so installer validation does not modify user configuration.
- Installer coverage: Add redirect, timeout, local fixture, and isolated PowerShell/Git Bash installation validation.
- Windows release build: Compile Unix raw-TTY passthrough only on Unix targets and ignore Unix-only prompt markers in the Git Bash event loop, restoring Windows CI builds.
- Interactive TTY passthrough: The Unix live wrapper now forwards raw terminal input while a command runs and restores the overlay at the next prompt. Interactive programs such as
gh auth login,fzf, editors, and password prompts can receive their native key input.
- macOS Bash/Zsh live overlay:
hs initenables the realtime Unix PTY-backed overlay for interactive macOS Bash and Zsh by default; no environment-variable opt-in or manual shell-profile edits are required.
- Bash login-shell setup: On macOS,
hs initmanages a dedicated block in~/.bash_profilethat loads~/.bashrc, allowing the Bash overlay to start reliably in Terminal and iTerm2. - Live shell CWD synchronization: Unix live children preserve their opening directory and emit an internal prompt marker after directory changes, keeping contextual suggestions aligned with
cdwithout changing the daemon protocol. - Shell-specific requests: The shared live runtime identifies Bash and Zsh independently in suggestion requests while keeping Git Bash on ConPTY and WSL2 Bash on its Unix PTY policy.
- Clean uninstall:
hs uninstallremoves the managed macOS Bash login block together with the HintShell Bash hook.
- Per-session escape hatches:
HINTSHELL_DISABLE_AUTO_BASH=1 bashandHINTSHELL_DISABLE_AUTO_ZSH=1 zshbypass the live wrapper for one session. - Native completion authority: The live overlay continues to defer path and flag completion to Bash/Zsh.
- Linux behavior: Linux Bash and Zsh remain on the native Tab/fzf integration outside WSL2.
- WSL2 Bash live overlay: Interactive WSL2 Bash sessions now use a Unix pseudo-terminal backend for the same realtime command overlay and Bash-native path/flag completion policy as Git Bash.
- WSL workspace directory: The Unix PTY child now explicitly inherits the parent terminal's current directory, so a WSL terminal opened at a workspace remains there after the live wrapper starts.
- Git Bash isolation: Git Bash remains on its existing Windows ConPTY backend.
- PowerShell isolation: PowerShell module, predictor, handlers, protocol, and overlay behavior are unchanged.
- Native Unix fallback: Linux/macOS Bash continue using the existing Tab/fzf picker outside WSL2.
- Cross-platform release builds: Compile the Git Bash live overlay only on Windows, with a clear unsupported-platform response elsewhere. This restores Linux and macOS release builds.
- Unix warning cleanup: Gate Windows-only tracing imports and preserve the daemon lock-file contents when opening it on Unix.
- Context-aware suggestions: The suggestion protocol now carries the current directory and shell. HintShell merges local/global history with bounded candidates for paths, Git branches/remotes, npm scripts, Docker, SSH hosts, and zoxide directories.
- Local history ranking: Commands used in the active directory receive a bounded boost without displacing stronger prefix matches or relevant global history.
- Git Bash live overlay auto-start:
hs initnow configures normal interactive Git Bash sessions to launchhintshell bashautomatically. SetHINTSHELL_DISABLE_AUTO_BASH=1to bypass it for one session.
- Git Bash completion policy: The live wrapper accepts command-prefix suggestions on Tab and defers path and flag input to native Bash completion.
- Git Bash overlay viewport: Up/Down selection scrolls a six-row viewport for longer result sets.
- Safe contextual I/O: Filesystem, workspace, and external-process generators use bounded output, deadlines, caches, and fail-closed behavior so suggestion requests do not block terminal input.
- PowerShell installation refresh:
hs initreplaces an existing HintShell integration block and updates the installed module asset instead of retaining an older module.
- Overlay at terminal bottom: Live Git Bash now caps visible rows to the space below the prompt, and hides the frame when even a minimal overlay would scroll the terminal. This prevents stale or duplicated render artifacts.
- Git Bash path resolution: Contextual filesystem lookup converts MSYS
/c/...paths before filesystem access and keeps the user's slash style in displayed suggestions.
- Daemon single-instance (Windows): Named mutex + pipe first-instance so IDE multi-terminal races no longer stack
hintshell-coreprocesses. - IDE offline / “Daemon is not running”: Start/status verify real IPC health; prefer
~/.hintshell/binover stalemodule/binaries; profile start uses a file lock and waits before killing orphans. - npm update while daemon running:
postinstallstops the daemon (IPC + force kill) before extracting binaries and runshintshell initsonpm i -g hintshell@latestcan overwrite locked.exefiles. hs update/ CLIupdate: Real upgrade path (stop → npm install → init/start), not version-check only; PowerShell update no longer writes.disabled.hintshell initfile lock: Force-kill before asset copy; skip self-overwrite of the running CLI on Windows; resolve module from~/.hintshell/modulewhen re-init frombin/.
- Clearer logs on
hs start/hs stop/hs status/hs update(success vs failure). - SQLite
busy_timeout+ WAL to reduce multi-process DB contention.
- PowerShell overlay layout: Compact mode on narrow terminals (≤3 items, short frequency labels, no emoji footer) to prevent line wrap and residual ghost text.
- Display-width aware rendering: Truncate/pad suggestion rows by terminal display columns; clear uses window-relative available rows.
- Bash/Zsh fzf resolver: Resolve a working
fzfbinary on Git Bash/MSYS — prefer real WinGet package path over non-executableWinGet/Linksshims. - Shell init hardening:
.bashrc/.zshrcinstall block uses POSIX paths and absolute~/.hintshell/bin/hintshell[.exe]so npm global never shadows hook generation. - fzf accept accuracy: Suggestion format no longer truncates the command string to 60 characters before Tab accept.
- Multi-line buffer (PowerShell): Suppress suggestion overlay when the edit buffer contains newlines so the panel does not paint over
>>continuation lines. - Git Bash
Permission deniedon fzf: Fixed Tab-to-suggest failing because MSYS cannot exec WinGet Links reparse-point shims. - Hook not loading after
source ~/.bashrc: Fixed path/order issues that caused old npmhintshellto be used forhook bashinstead of the installed binary.
- Shared
_hintshell_try_fzf/_hintshell_resolve_fzfhelpers for Bash and Zsh hooks. - Fallback when fzf is unavailable: accept top suggestion silently (no Permission denied noise).
- Multi-line skip for Bash/Zsh Tab picker (same product decision as PowerShell).
- Helper scripts:
scripts/test-overlay-layout.ps1,scripts/test-fzf-resolve-bash.sh.
- Update Flow Fix: Automatically stop running daemon during
hintshell initto prevent Windows File Lock errors (os error 32) and Unix stale background processes during updates. - Permissions Fix: Fix Unix socket connection failure (
os error 2) on macOS and WSL by automatically setting executable permission (chmod +x) on copied binaries. - Visual Clean: Comment out welcome suggestions guides on shell startup to keep output clean.
- Workflow Release: Configure release workflow to publish production release rather than pre-release.
- Update Lock Fix: Fixed "os error 32" on Windows by stopping the daemon before updating assets.
- Stable Update: Removed @beta tag from default update command to ensure stability.
- Persistent Recent Commands: Fixed an issue where the
recentcommand would disappear or get buried too quickly. - Direct DB Recent Match: Implementation of direct database query for the single most recent matching command to ensure high reliability.
- Balanced Ranking: Rebalanced weights between recency (40%) and frequency (35%) to keep recently used commands at the top longer.
- Smooth Decaying: Implemented a minute-based smoothing decay function for recency scores, preventing suggestions from "expiring" prematurely.
- Multi-pass Ranking: Smart suggestion ordering with 4-tier priority system:
- Recent — The most recently used command (within 30 min) appears first with
(recent)tag - Default — Built-in commands from the 600+ command library
- Most Used — The top frequently used command with
(most use)tag - Others — All remaining matching commands sorted by relevance
- Recent — The most recently used command (within 30 min) appears first with
- Source tracking: Database now tracks command origin (
uservsdefault) viasourcecolumn - Visual tier tags: Suggestion overlay displays
(recent)and(most use)labels alongside frequency count
- Bash/Zsh auto-start: Daemon now auto-starts when opening a new terminal session on macOS/Linux — no more manual
hs startrequired - Overlay sort override: Fixed PowerShell overlay re-sorting suggestions by frequency, which was overriding the server's multi-pass ranking order
- Default command seeding: Default commands are now inserted with a historical timestamp (
2000-01-01) andfrequency=0to prevent them from flooding the "recent" tier on first launch
- Added
sourcecolumn to SQLitehistorytable with automatic migration for existing databases - Added 5 new unit tests for multi-pass ranking logic and deduplication
- Updated
SuggestionItemprotocol to includesourcefield
- Initial public release
- Real-time suggestion overlay for PowerShell
- Tab-to-fzf integration for Bash/Zsh
- 600+ built-in default commands
- Frequency-based ranking
- Cross-platform support (Windows, macOS, Linux)