⚡ shellwise

Your shell history, but smart.

Inline auto-suggest, fuzzy search, and frecency ranking for your terminal — backed by a tiny background daemon so suggestions appear in ~1–3 ms without ever forking while you type.

Install · Features · Usage · How it works

Enter always runs what you typed. Suggestions never hijack your command — press Tab to step into the list only when you actually want one.

Why shellwise?

• 🧠 Suggestions that learn you — your real history, ranked by frecency (frequency × recency), so the commands you actually use float to the top and stale ones fade.
• ⚡ Instant, zero-fork — a persistent daemon answers every keystroke in ~1–3 ms over a Unix socket. No subprocess is ever spawned while you type.
• ⌨️ No Ctrl+R required — see matches inline as you type. (Ctrl+R is still there for full-screen fuzzy search when you want it.)
• 🔒 Private & local — everything lives in a SQLite file on your machine, reached through a 0600 Unix socket. Nothing leaves your computer.
• 📦 Zero config — one install, shell integration auto-injected, done.

🆚 How it compares

All of these are excellent tools — the difference is where the suggestions live:

| | shellwise | atuin | mcfly | zsh-autosuggestions | |---|:---:|:---:|:---:|:---:| | Suggests while you type | ✅ dropdown | ❌ Ctrl+R only | ❌ Ctrl+R only | ✅ ghost text | | Multiple candidates visible | ✅ | in Ctrl+R TUI | in Ctrl+R TUI | ❌ single | | Ranking | frecency | recency + context filters | neural network | most recent prefix match | | Fuzzy Ctrl+R search | ✅ | ✅ | ✅ | ❌ | | Cross-machine sync | ❌ local-only by design | ✅ optional e2e-encrypted | ❌ | ❌ | | Bash support | ✅ (Ctrl+R + auto-save) | ✅ | ✅ | ❌ zsh only |

TL;DR — if you want encrypted history sync across machines, use atuin. If you want a ranked dropdown under your prompt as you type — no keybind, no context switch — that's shellwise.

✨ Features

| | | |---|---| | Auto-save | Commands recorded automatically after a successful run (exit code 0). | | Inline auto-suggest | Dropdown appears as you type — no keybind needed. (zsh) | | Fuzzy search | Ctrl+R opens a full interactive search with real-time filtering. (zsh + bash) | | Frecency ranking | Frequency × recency, computed at query time — recent commands rank higher and decay naturally. | | Common commands | Suggests popular commands (git, npm, docker, …) even with empty history. | | Daemon mode | Persistent background process keeps suggest latency at ~1–3 ms, idles out after 30 min. | | Safe & self-healing | Reconnects automatically if the daemon restarts; preserves your command verbatim, even with \t/\n. |

📦 Install

This is a CLI tool — install it globally.

# Homebrew (recommended — standalone binary, nothing else to install)
brew install kurovu146/tap/shellwise

# Bun (requires Bun ≥ 1.0)
bun install -g shellwise

# npm (requires Bun ≥ 1.0 as the runtime)
npm install -g shellwise

The Homebrew formula (and the tarballs on GitHub Releases) ship a self-contained binary — you do not need Bun, Node, or any other runtime.

Shell integration is auto-injected into your ~/.zshrc or ~/.bashrc. Open a new terminal (or source your rc file) to activate.

# ~/.zshrc
eval "$(shellwise init zsh)"

# ~/.bashrc
eval "$(shellwise init bash)"

🚀 Usage

Just start typing. After 2+ characters, suggestions from your history appear inline.

While typing (zsh)

| Key | Action | |-----|--------| | Enter | Run the command you typed (or the highlighted suggestion, if you navigated into the list) | | Tab | Step into the list / next suggestion | | Shift+Tab | Previous suggestion | | → Right arrow | Accept the top suggestion inline (fills the line — doesn't run it) | | Esc | Dismiss suggestions |

Interactive search (Ctrl+R)

| Key | Action | |-----|--------| | type | Filter results in real time | | ↑ / ↓ | Navigate results | | Enter | Paste the selected command to your prompt | | Esc | Cancel |

🔧 Commands

Both shellwise and the short alias sw work:

sw search [--query <text>]     # Interactive fuzzy search (same as Ctrl+R)
sw delete [query]              # Interactively search & delete an entry
sw import [zsh|bash]           # Import your existing shell history
sw stats                       # Usage statistics
sw prune --days <n>            # Remove entries older than n days
sw daemon start|stop|status    # Manage the background daemon
sw version                     # Show version (and notify if an update exists)

sw import zsh      # from ~/.zsh_history
sw import bash     # from ~/.bash_history

sw delete          # browse all, pick one to delete
sw delete git      # pre-filter with "git"
sw prune --days 90 # drop everything older than 90 days

🧠 How it works

┌──────────────┐   Unix socket · ~1–3 ms   ┌────────────────────┐
│  Zsh / Bash  │ ◄═══════════════════════► │ shellwise daemon   │
└──────────────┘                           └──────────┬─────────┘
                                                      │
                                           ┌──────────▼─────────┐
                                           │  SQLite (WAL)      │
                                           │  history.db        │
                                           └────────────────────┘

• Shell hooks (preexec/precmd) capture each command after it runs.
• A persistent Unix-socket connection is opened once at shell init and reused for every keystroke — zero forks while typing.
• The daemon pre-warms prepared SQLite statements for instant lookups.
• Frecency = frequency × recency_weight, evaluated at query time so recency keeps decaying without any background job.
• The daemon idles out after 30 min and the shell reconnects on demand.

🗂️ Data & privacy

Everything is local to your machine:

~/.local/share/shellwise/history.db    # your history (SQLite)
~/.config/shellwise/                   # config (reserved)
/tmp/shellwise-<uid>.sock              # Unix socket  (mode 0600)
/tmp/shellwise-<uid>.pid               # daemon PID   (mode 0600)

✅ Requirements

• macOS or Linux
• Zsh (full experience) or Bash (auto-save + Ctrl+R search)
• Bun ≥ 1.0.0 — only when installing via bun/npm. The Homebrew and GitHub-release binaries are standalone.

⬆️ Update

sw version and sw stats tell you when a new release is out.

brew upgrade shellwise
bun install -g shellwise@latest
npm install -g shellwise@latest

🧹 Uninstall

brew uninstall shellwise      # or: bun remove -g shellwise / npm uninstall -g shellwise

Shell integration is removed automatically. If a stray line remains, delete it from your ~/.zshrc / ~/.bashrc:

# shellwise shell integration
eval "$(shellwise init zsh)"

Remove all stored data:

rm -rf ~/.local/share/shellwise

📄 License

MIT © Vu Duc Tuan