deja

Predictive ghost-text autosuggestions for zsh — smarter than history, lighter than a plugin.

---

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.

---

Features

• 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 run make test after make build
• Frecency scoring — blends frequency + recency with a 1-week exponential decay
• Ghost text inline — uses zsh's POSTDISPLAY 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
• Alternatives picker — press Tab to cycle through ranked alternatives without leaving the line

---

Installation

Homebrew (macOS & Linux)

brew install Giammarco-Ferranti/deja/deja && deja import && (grep -qF 'deja init zsh' ~/.zshrc 2>/dev/null || echo 'eval "$(deja init zsh)"' >> ~/.zshrc) && exec zsh

curl (any Linux/macOS, no Homebrew required)

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.

Oh My Zsh

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.

# 1. Install the deja binary. Skip (or remove) the `eval "$(deja init zsh)"` line it
#    offers to add to ~/.zshrc, since the plugin runs that for you:
brew install Giammarco-Ferranti/deja/deja          # or the curl installer above

# 2. Clone the plugin into Oh My Zsh's custom plugins dir:
git clone https://github.com/Giammarco-Ferranti/deja \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/deja

# 3. Add `deja` to plugins=(...) in ~/.zshrc:
#      plugins=( ... deja )

# 4. Import your history once and reload:
deja import && exec zsh

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 runs eval "$(deja init zsh)" for you, so if the installer already appended that line to ~/.zshrc, remove it. 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).

---

Setup

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 the eval line to your ~/.zshrc:

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

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

---

Key Bindings

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

Custom key bindings

Every binding above can be remapped by exporting the matching env var before eval "$(deja init zsh)" 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.

# defaults
export DEJA_CYCLE_KEY='^I'   # Tab    → cycle alternatives
export DEJA_TOGGLE_KEY='^X'  # Ctrl+X → suppress for the session
# these are unbound by default (→ and Ctrl+→ already accept via wrapped widgets):
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:

# Use Tab to accept the suggestion (and free Tab from cycling):
export DEJA_ACCEPT_KEY='^I' DEJA_CYCLE_KEY=

# Move alternatives-cycling off Tab so fzf/native completion keeps it:
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.

---

Tuning fuzziness

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

---

Troubleshooting

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 print pong.
2. Confirm the integration is loaded in your shell: eval "$(deja init zsh)" must be in ~/.zshrc and the shell re-sourced (exec zsh).
3. Ctrl+X toggles per-session suppression — start a new shell to clear it.

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.

pkill -f 'deja daemon'

A fresh terminal will auto-respawn it via the init script.

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

---

How It Works

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

Architecture

┌─────────────────┐     JSON/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, top-100 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.

---

Building from Source

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

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

• feat: ... → minor bump
• fix: ... → patch bump
• feat!: ... or a BREAKING 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.

---

Contributing

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.

Security

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

---

Uninstall

1. Remove the integration line from ~/.zshrc:

   eval "$(deja init zsh)"

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 optionally brew untap Giammarco-Ferranti/deja)
   • curl installer: rm "$(which deja)" (default location is ~/.local/bin/deja)

---

License

MIT — see LICENSE.

---

_{Made with ☕ and a friendly ghost.}