⚡ Why HintShell?

Most shells offer basic, single-line autocomplete. HintShell replaces that with a smart, interactive suggestion panel — a context-aware UI/UX upgrade right inside your terminal. It's the modern alternative to PSReadLine and zsh-autosuggestions.

| 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:

npm install -g hintshell@latest

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

PowerShell (Windows/Unix)

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

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

Zsh / Bash (macOS/Linux/Git Bash)

Tab-to-Suggest: To avoid conflicts with zsh-autosuggestions, HintShell activates when you press Tab.

• Type git + Tab : Opens a fuzzy picker with frequencies.
• Enter : Select and fill the command line.

Git Bash note: HintShell resolves fzf to a real executable (e.g. under WinGet Packages). If you previously saw Permission denied on WinGet/Links/fzf, reinstall/update to 0.2.0+, run hs init (or reload ~/.bashrc), and open a new terminal.

✨ What's new in 0.2.1

• Daemon single-instance + IDE terminal reliability (no stacked hintshell-core, IPC health checks).
• Safe update while running: npm i -g hintshell@latest / hs update stop the daemon before replacing Windows binaries.
• Clearer start/status/update logs. See CHANGELOG.md.

🔄 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.