Show HN: Deja predicts your next shell command without an LLM

Deja is a smarter replacement for zsh-autosuggestions. Instead of only surfacing commands that start with what you've typed, Deja uses fuzzy matching, directory awareness, and command sequence prediction to suggest what you actually want to run — as inline ghost text, after every keystroke, with zero latency.

No account. No sync server. No TUI. Just ghost text that knows where you are.

• Fuzzy matching — suggests commands even when you skip letters or mix up order
• Directory awareness — commands you run in~/projects/foo rank higher when you're in~/projects/foo
• Sequence prediction — knows that you usually runmake test aftermake build
• Frecency scoring — blends frequency + recency with a 1-week exponential decay
• Ghost text inline — uses zsh'sPOSTDISPLAY widget, not a separate pane
• Daemon architecture — one lightweight background process serves all terminal windows;<1ms response per keystroke
• Local-only — all data stays in a local SQLite database; nothing leaves your machine
• Respects your history settings — a leading space (HIST_IGNORE_SPACE ) or aHISTORY_IGNORE match keeps a command out of deja too, not just out of~/.zsh_history
• Alternatives picker — pressTab to cycle through ranked alternatives without leaving the line

brew install Giammarco-Ferranti/deja/deja && deja import && (grep -qF 'deja/init.zsh' ~/.zshrc 2>/dev/null || echo 'if [[ -r "$HOME/.local/share/deja/init.zsh" ]]; then source "$HOME/.local/share/deja/init.zsh"; else eval "$(deja init zsh)"; fi' >> ~/.zshrc) && exec zsh
curl -fsSL https://raw.githubusercontent.com/Giammarco-Ferranti/deja/main/install.sh | sh

Both commands install deja, import your existing zsh history, add the integration to ~/.zshrc (idempotent), and reload your shell. To audit the curl installer before running it, view it on GitHub.

If you manage zsh with Oh My Zsh, enable deja the idiomatic way, the same flow as zsh-autosuggestions. The binary still comes from Homebrew or the curl script; the plugin just sources deja's integration for you.

brew install Giammarco-Ferranti/deja/deja          # or the curl installer above

git clone https://github.com/Giammarco-Ferranti/deja \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/deja


deja import && exec zsh

If you use zinit, add this to your .zshrc:

zinit ice wait"0" lucid depth=1 pick"deja.plugin.zsh"
zinit light Giammarco-Ferranti/deja

zinit handles the Oh My Zsh plugin integration, so the activation lines in ~/.zshrc are not needed. Make sure the deja binary is installed separately via Homebrew or the curl installer.

Prefer not to clone the whole repo? Fetch just the plugin file instead:

mkdir -p ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/deja
curl -fsSL https://raw.githubusercontent.com/Giammarco-Ferranti/deja/main/deja.plugin.zsh \
  -o ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/deja/deja.plugin.zsh

Pick one activation, not both. The plugin loads deja's integration for you, so if the installer already appended activation lines to ~/.zshrc, remove them. Keeping both double-sources the integration.

Deja replaces zsh-autosuggestions, so don't list both in plugins=(). If deja detects zsh-autosuggestions is loaded it stands down (see Troubleshooting).

The install commands above already do this for you. If you skipped them and have the binary on $PATH some other way, run these once to import your zsh history and activate the integration:

deja import
eval "$(deja init zsh)"

By default deja import reads your zsh history from $HISTFILE (when it's exported), falling back to ~/.zsh_history. If your history lives elsewhere or $HISTFILE is set in ~/.zshrc without export, so child processes can't see it point deja at the file explicitly:

deja import --file /path/to/history

To make it permanent, add this to your ~/.zshrc:

if [[ -r "$HOME/.local/share/deja/init.zsh" ]]; then
  source "$HOME/.local/share/deja/init.zsh"
else
  eval "$(deja init zsh)"
fi

deja init zsh does not print the integration script — it writes it to ~/.local/share/deja/init.zsh and prints a source line for that file. So eval "$(deja init zsh)" spends a full binary launch, ~25–36 ms on every shell you open, regenerating a file that is almost always byte-identical. Sourcing the file directly skips that; the eval above is only the first-run bootstrap, for before the file exists.

Deja keeps the cached script current itself. Each shell compares the installed binary's stat identity against the one baked into the script — 0.083 ms, no subprocess — and if they differ, regenerates it in the background. The shell that noticed carries on with the old script; the next one picks up the new. So an upgrade never costs you a slow shell startup, and never leaves you on a stale integration either.

Deja auto-spawns its daemon on first use and keeps it running across sessions.

Key	Action	Rebind with
→ (right arrow)	Accept full suggestion	DEJA_ACCEPT_KEY (extra key)
Ctrl+→	Accept next word only	DEJA_WORD_ACCEPT_KEY (extra key)
Shift+→	Cycle fuzzy preset forward (tight → smart → loose)	DEJA_CYCLE_FUZZY_KEY
Shift+←	Cycle fuzzy preset backward (loose → smart → tight)	DEJA_CYCLE_FUZZY_BACK_KEY
Shift+↑	Toggle ghost text on an empty prompt (persisted, global)	DEJA_TOGGLE_EMPTY_KEY
Tab	Open inline alternatives picker	DEJA_CYCLE_KEY
Ctrl+X	Suppress current suggestion (session-wide)	DEJA_TOGGLE_KEY
(unbound)	Dismiss the current ghost (this line only)	DEJA_DISMISS_KEY

Accept the ghost suggestion with →, not Enter. Enter executes whatever's literally in your buffer; → is what commits the ghost into the buffer first.

Every binding above can be remapped by exporting the matching env var before the lines that load deja in your ~/.zshrc. Values are zle key sequences (e.g. ^I is Tab, ^X is Ctrl+X, ^[[1;2C is Shift+→); run bindkey -L or pipe a keypress through cat -v to discover a key's sequence. Set any var to empty to leave that key unbound.

export DEJA_CYCLE_KEY='^I'                 # Tab     → cycle alternatives
export DEJA_TOGGLE_KEY='^X'                # Ctrl+X  → suppress for the session
export DEJA_CYCLE_FUZZY_KEY='^[[1;2C'      # Shift+→ → next fuzzy preset
export DEJA_CYCLE_FUZZY_BACK_KEY='^[[1;2D' # Shift+← → previous fuzzy preset
export DEJA_TOGGLE_EMPTY_KEY='^[[1;2A'     # Shift+↑ → flip empty-prompt suggestions
export DEJA_ACCEPT_KEY=       # accept full suggestion on a dedicated key
export DEJA_WORD_ACCEPT_KEY=  # accept the next word on a dedicated key
export DEJA_DISMISS_KEY=      # clear the ghost for this line (unlike Ctrl+X, the session keeps suggesting)

DEJA_DISMISS_KEY (deja-clear) differs from DEJA_TOGGLE_KEY (deja-toggle): dismiss only wipes the ghost on the current line, while toggle suppresses suggestions for the whole session until you toggle back or start a new shell.

Examples:

export DEJA_ACCEPT_KEY='^I' DEJA_CYCLE_KEY=

export DEJA_CYCLE_KEY='^N'

Esc as dismiss: binding DEJA_DISMISS_KEY='^[' (Esc) directly is discouraged — Esc is the prefix byte for arrow keys, function keys, and vi-mode, so a bare ^[ binding can break those. Prefer a non-prefix key (e.g. ^G), or set it knowing the tradeoff.

Deja paints its suggestion through zsh's region_highlight, so the ghost text accepts any style string zsh understands. The default is fg=8 (ANSI bright black), which renders as dim grey on most themes.

export DEJA_HIGHLIGHT_STYLE='fg=cyan'

The grammar is the same one zsh-autosuggestions uses for ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE, so an existing style carries over unchanged:

Value	Effect
fg=8	dim grey, the default
fg=cyan	named colour
fg=244	index into the 256 colour palette
fg=cyan,bg=white	foreground plus background
fg=cyan,bold,underline	attributes; standout andblink also work

Export it before the integration loads. The variable is read once, at the moment the init script is sourced, and it only applies when already unset. Setting it below the source line in ~/.zshrc has no effect, so put it above:

export DEJA_HIGHLIGHT_STYLE='fg=cyan,bold'   # must come first

if [[ -r "$HOME/.local/share/deja/init.zsh" ]]; then
  source "$HOME/.local/share/deja/init.zsh"
else
  eval "$(deja init zsh)"
fi

If the default is too faint on your colour scheme, fg=244 or fg=8,bold usually lifts it clear of the background without competing with the text you are typing.

Deja's matcher accepts any in-order subsequence of the characters you've typed. By default it stops the typed letters from sprawling too far apart in a candidate — gco will match git checkout, but won't match git remote add origin. Pick a preset to tune that strictness:

Preset	Behavior	Example: typing gco
loose	typed letters can be far apart (up to 8 chars between)	gco →git checkout -- README
smart	typed letters stay close together (up to 4 chars between) — default	gco →git checkout main
tight	typed letters must be near-adjacent (up to 1 char between)	gco →gco ,g.co ,gc.o

Change the preset on the fly (takes effect immediately, persists across restarts):

deja fuzzy           # show current preset + examples
deja fuzzy tight     # set the preset
deja fuzzy cycle     # advance to the next preset  (tight → smart → loose → tight)
deja fuzzy back      # step to the previous preset (loose → smart → tight → loose)

Or cycle without leaving the line — press Shift+→ (forward) or Shift+← (backward) at any prompt and the next preset is applied immediately. The ghost suggestion repaints under the new mode in the same frame, and a picker-style confirmation appears below the prompt showing where you are in the ladder:

deja: fuzzy    tight    *smart*    loose

Rebind via DEJA_CYCLE_FUZZY_KEY / DEJA_CYCLE_FUZZY_BACK_KEY (set either to empty to disable that direction; tmux users may need set -g xterm-keys on for the default Shift+arrow sequences to pass through).

Or override per shell session via environment variable:

export DEJA_FUZZY=smart   # before the daemon starts; takes precedence over the saved preset

By default, on a fresh prompt — before you've typed anything — Deja predicts the command you're most likely to run next, based on command-sequence, frecency, and directory signals, and shows it as ghost text. If you'd rather see nothing until you start typing, turn empty-prompt suggestions off:

deja empty            # show whether empty-prompt suggestions are on
deja empty off        # never suggest on an empty prompt (aliases: deja empty hide)
deja empty on         # restore the default (aliases: deja empty show)
deja empty toggle     # flip the setting, printing just the new state (on|off)

Or flip it without leaving the line — press Shift+↑ at any prompt. The ghost appears or disappears in the same frame, and a picker-style confirmation shows the new state below the prompt:

deja: empty   *on*    off

Rebind via DEJA_TOGGLE_EMPTY_KEY (set it to empty to leave Shift+↑ unbound; tmux users may need set -g xterm-keys on for the default Shift+arrow sequences to pass through). Note that — like fuzzy cycling — the keypress changes the persisted, global setting, not just the current session.

Changes take effect immediately if the daemon is running and persist across restarts (saved to ~/.local/share/deja/config). Override per shell session with an environment variable:

export DEJA_EMPTY=off   # before the daemon starts; takes precedence over the saved setting

This is a global, persisted setting. It's different from Ctrl+X, which suppresses all suggestions for the current shell session only (see Key Bindings).

Deja records the commands you run, so it honours the same rules zsh uses to decide what not to remember. If zsh won't keep a command, deja won't either.

Keep one command out of history with a leading space. With setopt hist_ignore_space (set it in ~/.zshrc; some frameworks enable it by default), any line starting with a space or tab is discarded by zsh. Deja skips it too:

setopt hist_ignore_space
 export AWS_SECRET_ACCESS_KEY=wJal…   # leading space: neither zsh nor deja records this

The check runs inside the shell hook, before deja is invoked, so the command is never handed to another process and never appears in ps.

Keep a pattern out of history with HISTORY_IGNORE. Deja applies your pattern the way zsh does, as a glob against the whole line:

HISTORY_IGNORE='(*AWS_SECRET*|*--password*)'

Ignored commands break the prediction chain. A skipped command is also dropped as the "previous command" used for sequence prediction, so it can't resurface indirectly through the sequences table.

One deliberate difference from zsh. Deja drops space-prefixed commands even if you haven't set hist_ignore_space, because the daemon can't see your shell's setopt state and errs toward forgetting. Those commands stay in your zsh history as usual; they're simply not learned by deja. Suggestions are always offered trimmed, so nothing useful is lost.

Commands recorded before you upgraded are still in the database. To start over from your current history:

pkill -f 'deja daemon'
rm ~/.local/share/deja/deja.db
deja import

deja import applies the same rules, so space-prefixed lines in your history file are skipped.

Deja stores commands in plaintext in a local SQLite database and never sends them anywhere. It does not redact secrets embedded in otherwise ordinary commands such as curl -H "Authorization: ...", so use the leading space for those.

Every subcommand supports --help (e.g. deja query --help) for flag-level details. The most common issues:

Suggestions aren't appearing.

1. Check the daemon is reachable: deja ping should printpong .
2. Confirm the integration is loaded in your shell: ~/.zshrc must source~/.local/share/deja/init.zsh (seeSetup ) and the shell must have been re-sourced (exec zsh ).
3. Ctrl+X toggles per-session suppression — start a new shell to clear it.

Ghost text is too faint to read. The suggestion is painted fg=8 (dim grey) by default, which some terminal themes render almost invisibly. Choose a brighter style with DEJA_HIGHLIGHT_STYLE, exported above the source line in ~/.zshrc. See Ghost text appearance.

Using another inline-suggestion plugin. Deja renders its own ghost text and replaces zsh-autosuggestions — don't run both. If Deja detects zsh-autosuggestions is loaded it prints a one-line notice and stands down (rather than wrapping the same ZLE widgets, which can wedge the line editor). To use Deja, remove zsh-autosuggestions from plugins=() in ~/.zshrc and restart your shell.

The daemon seems stuck.

deja daemon --restart

Or stop it and let a fresh terminal auto-respawn it via the init script:

pkill -f 'deja daemon'

Suggestions still work but feel slow after upgrading deja. Daemons outlive shell sessions, so the one still running is from the previous version. New shells detect this and fall back to a slower path that keeps working; deja daemon --restart replaces it. Upgrading from a version older than the one that introduced --restart needs a one-time pkill -f 'deja daemon' instead, since those daemons left no pidfile to find them by.

Stale socket after a crash.

rm ~/.local/share/deja/sock

Then open a new shell.

Reset the database (start over from current ~/.zsh_history).

pkill -f 'deja daemon'
rm ~/.local/share/deja/deja.db
deja import

Where data lives.

Path	Purpose
~/.local/share/deja/deja.db	SQLite database (history, stats, sequences)
~/.local/share/deja/sock	Unix socket the daemon listens on
~/.local/share/deja/init.zsh	Generated zsh integration script

Everything is per-user: each account gets its own database, socket, and daemon under its own $HOME. The directory is 0700 and the database files are 0600, so other local accounts can't read your history. Deja re-applies those modes every time it runs, which repairs installs created by older versions with no action from you.

Deja is built around four signals that are combined into a single composite score:

score = 1.0 × fuzzy
      + 0.4 × frecency
      + 0.3 × directory_affinity
      + 0.5 × sequence_score

Signal	What it measures
Fuzzy	Subsequence match quality with bonuses for consecutive characters, word boundaries, and prefix hits
Frecency	Log-scaled frequency combined with exponential recency decay (1-week half-life)
Directory affinity	How often you've run this command from the current directory
Sequence score	Probability that this command follows the one you just ran

Scoring only runs over commands that are plausible continuations of what you typed. If any command in your history starts with the text on the line, only those are considered — typing cd suggests a cd … you have actually run, never claude --resume just because c…d…␣ happens to be hiding in it. If nothing starts with the line but its first word is a command you've run, the suggestion stays inside that command, so git ceckout still finds git checkout main.

Fuzzy expansion applies when the text is not a command you've run: gco → git checkout is untouched. The flip side is that an anchored line with nothing to match shows no ghost text at all, rather than an unrelated command.

┌─────────────────┐        Unix socket        ┌──────────────────────┐
│   zsh widget    │ ──────────────────────▶   │   deja daemon        │
│  (per keystroke)│ ◀──────────────────────   │  (single process,    │
└─────────────────┘    suggestion (<1ms)      │   all terminals)     │
                                              └──────────┬───────────┘
                                                         │
                                                   SQLite (WAL)
                                              commands · stats · seqs

The daemon loads all state into memory at startup (map[string]*CommandStat, directory affinities, sequence pairs) and uses a sync.RWMutex so reads never block each other. Writes (command recording) take microseconds.

If the daemon is unavailable, deja query falls back to a direct SQLite read automatically. That path ranks in two passes — once on fuzzy, frecency and sequence signal, then again over the top 50 with directory affinities fetched just for them — so a keystroke costs a few queries rather than one per command in your history.

git clone https://github.com/Giammarco-Ferranti/deja.git
cd deja
make build        # produces ./bin/deja

go test ./...     # run all tests
go vet ./...      # lint

Releases are automated via release-please and driven by conventional commits on main:

• feat: ... → minor bump
• fix: ... → patch bump
• feat!: ... or aBREAKING CHANGE: footer → major bump
• chore: ,docs: ,test: ,refactor: → no version bump

After qualifying commits land on main, the release-please workflow opens (and keeps updating) a Release PR that bumps .release-please-manifest.json and updates CHANGELOG.md. Merging that PR is the release action — it creates the vX.Y.Z git tag, which triggers release.yml to run the test suite and (only on green) publish binaries via GoReleaser and update the Homebrew tap.

Maintainers should not run git tag manually.

Contributions are welcome — see CONTRIBUTING.md for setup, workflow, and commit conventions. For anything larger than a small fix, please open an issue first so we can align on direction.

The scorer (internal/scorer/) is the most iteration-heavy part of the codebase — the four signal weights are the best place to experiment if you want to improve suggestion quality.

Please report vulnerabilities privately via GitHub's "Report a vulnerability" button on the repo's Security tab, not as public issues.

Your command history is stored in plaintext in a local SQLite database. Deja keeps ~/.local/share/deja/ at 0700 and the database files at 0600 so other accounts on the same machine cannot read it (see Where data lives). It is not encrypted at rest, so anyone who can already act as you, or as root, can read it. For how deja handles sensitive commands, and how to keep one out of the database, see Privacy.

1. Remove the activation lines from ~/.zshrc — whichever form you used:

if [[ -r "$HOME/.local/share/deja/init.zsh" ]]; then
  source "$HOME/.local/share/deja/init.zsh"
else
  eval "$(deja init zsh)"
fi

2. Stop the running daemon:

pkill -f 'deja daemon'

3. Delete local data (history DB, socket, generated init script):

rm -rf ~/.local/share/deja/

4. Remove the binary, depending on how you installed it:

• Homebrew:brew uninstall deja (and optionallybrew untap Giammarco-Ferranti/deja )
• curl installer:rm "$(which deja)" (default location is~/.local/bin/deja )

MIT — see LICENSE.

_{Made with ☕ and a friendly ghost.}

source & further reading

github.com — original article Deterministic Rule based auto-approver for Claude/Codex Show HN: Mu – a mouse-driven terminal code editor written in terrible Rust Vaenyx – A personal AI app for family