⚡ Why HintShell?

Most shells offer basic, single-line autocomplete. HintShell adds a smart, interactive suggestion panel while keeping each shell authoritative for its own completion behavior: Bash and PSReadLine still own path and flag completion, and HintShell only supplies advisory command suggestions.

| Feature | HintShell | PowerShell (PSReadLine) | Zsh (zsh-autosuggestions) | Bash | Git Bash | Fish | |---|:---:|:---:|:---:|:---:|:---:|:---:| | Suggestion UI | Scrollable list | Single inline ghost | Single inline ghost | None | None | Single inline ghost | | Prefix matching | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | Frequency ranking | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | | Smart ranking | ✅ Recent → Default → Most Used → Others | ❌ | ❌ | ❌ | ❌ | ❌ | | Command descriptions | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Cross-shell | ✅ | PowerShell only | Zsh only | Bash only | — | Fish only | | Learns from history | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | | Auto-start daemon | ✅ | N/A | N/A | N/A | N/A | N/A | | 600+ built-in commands | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Works with any terminal | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

🚀 Installation (Recommended)

Follow these steps in order to get HintShell running on your machine.

1. Install Dependencies (macOS / Linux / Git Bash)

HintShell uses fzf to render the suggestion picker on Bash/Zsh (including Git Bash on Windows).

• macOS: brew install fzf
• Linux (Ubuntu/Debian): sudo apt install fzf
• Windows (Git Bash): winget install junegunn.fzf (or install fzf another way). PowerShell overlay does not require fzf.
• Windows PowerShell: No extra dependencies for the real-time overlay.

2. Install HintShell

Install via npm to get the latest pre-built binaries for your platform. Add --foreground-scripts to show the binary download, extraction, and setup output (this is also what hs update uses):

npm install -g hintshell@latest --foreground-scripts

3. Initialize Shell Integration

Run the init command to automatically configure your shell (.zshrc, .bashrc, or PowerShell profile):

hs init

4. Restart Terminal

Restart your terminal or reload your shell config to activate the hooks:

# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc

# PowerShell
. $PROFILE

📖 Usage

Git Bash / WSL2 Bash

After hs init, opening a normal interactive Git Bash or WSL2 Bash session automatically starts hintshell bash, which renders a local live overlay as you type. fzf is not required for this live mode.

• ↑ / ↓ navigate HintShell suggestions; Esc closes the overlay; Enter executes through Bash.
• Tab accepts only a compatible command suggestion. Path input such as cd src/comp, flags such as git --ver, and empty overlays are forwarded to Bash's native completion.
• The overlay adapts near the bottom of the terminal: it shows fewer rows when space is limited and stays hidden when a complete frame would scroll the terminal.
• To bypass the wrapper for one shell, run:

HINTSHELL_DISABLE_AUTO_BASH=1 bash

• Git Bash keeps its existing Windows ConPTY backend. WSL2 uses a separate Unix pseudo-terminal backend and preserves the terminal's current working directory; neither changes PowerShell integration.
• Native Linux Bash retains the existing Tab/fzf picker instead of starting the live wrapper.
• Set HINTSHELL_BASH to an explicit bash.exe path on Git Bash. Set HINTSHELL_DISABLE_LIVE_OVERLAY=1 to reject the wrapper in unsupported terminals.

Preview limitation: the live wrapper requires an ANSI-capable terminal. For full-screen terminal applications, bypass the wrapper and open them from a normal Bash session.

Git Bash Fast in VS Code

A VS Code Git Bash profile using --norc --noprofile intentionally skips ~/.bashrc, so it also skips HintShell's standard Bash hook. Create a separate, minimal rcfile instead:

hs init --git-bash-fast

The command creates ~/.hintshell/git-bash-fast.bashrc, which keeps the green/yellow prompt, initializes HintShell, and does not source your aliases, plugins, .bashrc, or .bash_profile. It prints a Git Bash Fast + HintShell profile for VS Code. Add that profile to user settings and select it manually; HintShell does not edit settings.json or change terminal.integrated.defaultProfile.windows.

The emitted profile has this shape (the rcfile path reflects your own user directory):

"terminal.integrated.profiles.windows": {
  "Git Bash Fast + HintShell": {
    "path": "C:\\Users\\<you>\\.hintshell\\bin\\hintshell.exe",
    "args": ["bash", "--rcfile", "/c/Users/<you>/.hintshell/git-bash-fast.bashrc", "-i"],
    "icon": "terminal-bash"
  }
}

The live overlay needs VS Code's ANSI-capable integrated terminal and Windows ConPTY. Select the original Git Bash Fast profile for a session without HintShell. Within the dedicated profile, set HINTSHELL_DISABLE_AUTO_BASH=1 before starting Bash to bypass the wrapper for a session.

macOS Bash / Zsh live overlay

On macOS, hs init configures the realtime overlay automatically for interactive Bash and Zsh sessions. For Bash login shells, it also adds a managed block to ~/.bash_profile that loads ~/.bashrc, so the overlay starts in macOS Terminal and iTerm2 without manual profile edits.

hs init

Open a new terminal after initialization. The wrapper starts the same shell as a child through the Unix pseudo-terminal backend. It preserves the opening directory and synchronizes the current directory after each prompt, so contextual suggestions follow cd changes.

• Tab keeps native Bash/Zsh path and flag completion authoritative; HintShell accepts only compatible command-prefix suggestions.
• Interactive programs such as gh auth login, fzf, vim, and nano receive raw terminal input while running; the overlay resumes automatically at the next prompt.
• Bash escape hatch: HINTSHELL_DISABLE_AUTO_BASH=1 bash
• Zsh escape hatch: HINTSHELL_DISABLE_AUTO_ZSH=1 zsh
• Run hs uninstall to remove both the shell hook and the managed Bash login block.
• Use an escape hatch for full-screen terminal applications or any profile whose startup plugins are not compatible with a PTY wrapper.

Zsh / Bash (macOS/Linux)

Tab-to-Suggest uses fzf when available. Type git and press Tab to open a ranked command picker; Enter fills the command line. If fzf is unavailable, HintShell uses the top matching command without emitting an executable-path error.

Context-aware suggestions & Smart Directory Navigation

Each request includes the current working directory and shell. HintShell merges bounded contextual candidates with local and global history, then ranks the combined list once.

• Smart cd Suggestions: Typing cd automatically lists directories in your current folder sorted by recent modification time (mtime), while keeping your #1 most frequent/recent command on top. Shortcut completions like cd .. and cd - are included out of the box.
• Deep Tech Stack Detection: Automatically senses workspace marker files (pnpm-lock.yaml, bun.lockb, yarn.lock, Cargo.toml, docker-compose.yml, .git/index) to recommend contextual dev, build, test, and git workflow commands.
• Typo Tolerance & Substring Matching: Tolerates single-character command typos (gti $\rightarrow$ git, dcoker $\rightarrow$ docker) with automatic substring (contains) fallback matching.
• Paths & Tool Arguments: Paths for supported argument positions, including cd, pushd, mkdir, rmdir, cat, rg, git add, and docker build.
• Entity Suggestions: Git branches/remotes, npm-family scripts, Docker entities, SSH hosts, and zoxide directories when the command and local runtime are available.
• Privacy & Performance: Filesystem scans, workspace detection, and external commands are bounded, cached where appropriate, and fail closed. Context candidates never write themselves to command history.

🎨 Customization (~/.hintshell/config.toml)

HintShell creates a configuration file at ~/.hintshell/config.toml automatically on initial setup:

# Popup border color palette:
# - "apple" / "siri" / "glow" (Apple Intelligence 24-bit TrueColor Cyber Glow)
# - "rainbow" / "gemini" (Vibrant multi-color spectrum)
# - Solid tones: "purple" (default), "blue", "cyan", "green", "yellow", "orange", "pink", "magenta", "minimal"
border_color = "apple"

# Maximum number of suggestions shown in popup overlay (default: 6)
max_visible = 6

# Enable inline ghost text completion preview (default: true)
ghost_text = true

PowerShell (Windows/Unix)

Real-time Overlay: Suggestions appear automatically as a floating panel beneath your cursor as you type.

• ↑ / ↓ : Navigate
• Tab : Accept
• Esc : Close

✨ What's new in 0.3.4

• hs init automatically enables the live overlay for macOS Bash and Zsh; no opt-in environment variable is required.
• macOS Bash login sessions load .bashrc through a HintShell-managed block in .bash_profile, so the overlay works in Terminal and iTerm2.
• hs uninstall removes both the shell hook and HintShell's managed Bash login block.
• Git Bash and WSL2 retain their live-overlay backends; Linux Bash/Zsh outside WSL2 continue using Tab/fzf.

🔄 Updating

While the daemon is running, Windows locks hintshell-core.exe. Use:

# Recommended
hs update

# Or raw npm — postinstall stops the daemon and runs init
npm i -g hintshell@latest

If you still hit a file lock (os error 32 / "being used by another process"):

hs stop
# or: taskkill /F /IM hintshell-core.exe
npm i -g hintshell@latest
hintshell init

🗑️ Uninstallation

If you need to remove HintShell, it now comes with a clean uninstaller that handles everything for you:

# 1. Run the official uninstaller
hs uninstall

# 2. (Optional) Remove the NPM package
npm uninstall -g hintshell

Note: hs uninstall stops the daemon, removes hook lines from your shell configs, and deletes binaries from ~/.hintshell/bin, but keeps your history database (history.db) safe.

🏗️ CLI Reference

hs status      # Check if the daemon is running and see stats
hs start       # Manually start the daemon
hs stop        # Stop the daemon
hs update      # Stop daemon, npm install -g, init, restart
hs uninstall   # Completely remove shell integration and binaries

🏗️ Architecture

HintShell is a client-daemon system. It does not replace your terminal or shell. It plugs in via a thin hook.

┌─────────────────────────────────┐
│  Your Terminal                  │
│  (Windows Terminal, iTerm2,     │
│   Alacritty, any terminal)      │
│                                 │
│  ┌───────────────────────────┐  │
│  │  Your Shell               │  │
│  │  (PowerShell / Bash / Zsh)│  │
│  │       ▲                   │  │
│  │       │ hook / module     │  │
│  │       ▼                   │  │
│  │  ┌─────────┐    IPC    ┌──────────────┐
│  │  │   hs    │◄─────────►│ hintshell    │
│  │  │  (CLI)  │ Named Pipe│ -core        │
│  │  └─────────┘  or UDS   │ (Daemon)     │
│  │                        │ SQLite+Fuzzy │
│  │                        └──────────────┘
│  └───────────────────────────┘  │
└─────────────────────────────────┘

🤝 Contributing & License

Contributions are welcome! Built with 🦀 Rust for speed and safety. Licensed under MIT.