Who deja is for#
zsh power users outgrowing zsh-autosuggestions
Developers who find that standard history prefix matching misses most of what they actually want to type. deja imports your existing zsh history on first run, so the switch is low-friction. The fuzzy matching and sequence prediction start adding value immediately against a full history file.
Skip if:
If you rely on zsh-autosuggestions, you must remove it before enabling deja; the two plugins cannot run together. If plain prefix matching already covers your workflow, the added complexity of a background daemon is not worth it.
Security-conscious developers with sensitive terminal sessions
Developers who handle credentials, internal hostnames, or project-specific paths in the terminal and want smarter suggestions without sending that history to an external server. deja's local-only operation satisfies privacy requirements that Warp and GitHub Copilot CLI cannot meet by design.
Skip if:
If you already use a cloud-backed terminal you are comfortable with and privacy of shell history is not a concern, deja's local-only constraint removes features like cross-device sync that you may rely on.
The problem it solves#
zsh-autosuggestions is useful but limited. It only surfaces commands that start with exactly what you have already typed, so fuzzy matches and common command sequences go unrecognized. Type a few letters of a command you run constantly in a specific directory, and the built-in engine has no way to surface it if your prefix does not match the beginning of a stored line.
The commercial terminals and AI shell tools that solve this challenge, including Warp and GitHub Copilot CLI, do so by routing shell history to their servers. For developers handling credentials, internal hostnames, or sensitive project paths in the terminal, that is a real privacy cost. There is no open option that combines accurate, low-latency shell suggestions with strict local-only operation.
How it solves it#
Fuzzy Matching Across Your Entire History
Suggests commands even when you skip letters or type them out of order. Uses a configurable preset (tight, smart, or loose) to control how far apart matched characters can be in a candidate. With the default smart preset, typing `gco` can surface `git checkout main` even if that string never started with `gco` in your history. Presets can be toggled live at the prompt with Shift+arrow keys.
Directory-Aware Ranking
Commands you run in a specific directory rank higher when you are in that same directory. Switching projects shifts the suggestion ranking automatically. A command like `npm run dev` climbs to the top when you are in your frontend project folder and drops back down when you move to a different directory. No manual configuration is needed.
Command-Sequence Prediction
Learns which commands you typically run in sequence. If you consistently run `make test` after `make build`, deja learns that pair and predicts `make test` on the next empty prompt after `make build` completes. Sequence data is stored locally in the SQLite database alongside frecency data.
Frecency Scoring with Exponential Decay
Blends command frequency with recency using a 1-week exponential decay. Commands you ran yesterday outrank commands from six months ago at the same frequency. Commands you run daily consistently score above one-off commands from the same period. The scoring updates after every command with no manual tuning required.
Sub-Millisecond Background Daemon
A single lightweight Go daemon runs in the background and serves all open terminal windows simultaneously. Response time per keystroke is under 1ms. The daemon auto-spawns on first use, restarts automatically after an upgrade, and survives shell reloads. No separate service manager or configuration is needed.
Strengths and trade-offs#
Strengths
- Fully local with no account or subscriptiondeja stores all data in a local SQLite file and the daemon never opens a network connection. Unlike Warp or GitHub Copilot CLI, there is no sign-up, no API key, and no cloud account required. The tool works offline and costs nothing beyond the machine it runs on.
- Respects zsh privacy settings nativelyCommands prefixed with a space, when HIST_IGNORE_SPACE is set, are skipped by both zsh and deja. Patterns matching HISTORY_IGNORE are excluded from the deja database as well, not just from ~/.zsh_history. A skipped command is also dropped as the previous command for sequence prediction, so it cannot resurface indirectly through the sequences table.
- MIT license with no commercial restrictionsMIT licensed, meaning personal, commercial, and modified use are unrestricted. No AGPL network-service clauses to navigate for self-hosted products, and no proprietary lock-in if you need to patch the binary or fork the integration for your team.
Trade-offs
- -zsh-only; no bash, fish, or other shell supportdeja uses zsh-specific internals including POSTDISPLAY for ghost text rendering and ZLE widget wrapping for key bindings. Bash, fish, and other shells are not supported. If your team uses a mix of shells or relies primarily on bash, deja provides no value and the background daemon is unnecessary overhead.
- -History-driven: cannot suggest commands you have never typeddeja's suggestions always come from your own zsh history. It cannot generate novel commands from a description, unlike GitHub Copilot CLI or Warp's AI features. For developers who use their terminal to learn new CLIs or ask for command syntax they do not know yet, a history-based tool is insufficient on its own.
deja vs alternatives#
deja vs Warp
Warp is a terminal emulator with built-in AI shell suggestions and cloud-synced history. deja is a zsh plugin that adds predictive autosuggestions to any terminal emulator. They overlap on the shell suggestion problem but serve fundamentally different deployment models.
| Feature | deja | Warp |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Local binary, no server | No; cloud-connected terminal |
| Shell history | Local SQLite, never transmitted | Synced to Warp's cloud |
| Platform | Any terminal (zsh only) | Warp terminal only |
| Cost | Free | Free tier with paid plans |
deja is the better choice when you want smarter suggestions inside your existing terminal setup without switching terminal emulators, or when privacy of shell history is a hard constraint. Warp is worth considering when you want a fully integrated AI-powered terminal experience with cross-device history sync and LLM-generated command assistance beyond what your own history contains.
deja vs GitHub Copilot CLI
GitHub Copilot CLI provides AI-powered shell suggestions via a language model and requires a GitHub Copilot subscription. deja provides history-driven suggestions with no subscription, no API key, and no network dependency.
| Feature | deja | GitHub Copilot CLI |
|---|---|---|
| License | MIT | Proprietary |
| Suggestion source | Local zsh history | OpenAI language model |
| Cost | Free | Copilot subscription required |
| Offline use | Yes | No |
| Novel command generation | No | Yes |
deja wins on cost, privacy, and offline availability. GitHub Copilot CLI wins when you need to generate commands you have never typed before, or when you want natural language to shell command translation. For developers who primarily want to navigate their own command history faster and more accurately, deja requires no account and adds no latency from a network call. For developers who use the terminal to discover new CLI tools or generate complex one-off commands, GitHub Copilot CLI's language model backend provides value deja cannot match.
Install and self-host#
Install deja via the curl installer on any macOS or Linux system; the script handles setup, history import, and shell integration.
```bash
curl -fsSL https://raw.githubusercontent.com/Giammarco-Ferranti/deja/main/install.sh | sh
```What it's built on#
- Languages
- Go
FAQ#
Is deja free to use?
Yes. deja is MIT licensed and has no paid tier, managed cloud option, or subscription. You install it locally and run it at no cost. The only dependency is a working zsh installation on macOS or Linux.
Does deja send my shell commands to any external server?
No. All command history is stored in a local SQLite database at ~/.local/share/deja/deja.db. The background daemon does not open any network connections. Your shell history stays on your machine.
Can deja run alongside zsh-autosuggestions?
No. deja renders its own ghost text and wraps the same ZLE widgets as zsh-autosuggestions. If it detects zsh-autosuggestions is loaded, it prints a warning and stands down rather than competing. To use deja, remove zsh-autosuggestions from your plugins list and restart your shell.
What shells does deja support?
Only zsh. deja uses zsh-specific internals including POSTDISPLAY for ghost text rendering and ZLE widget wrapping for key bindings. There is no support for bash, fish, or POSIX shells.
How does deja learn command sequences like running make test after make build?
After every command completes, deja records the pair of (previous command, current command) in a local sequences table in its SQLite database. The next time you run the first command, deja uses this table to weight the predicted follow-up higher in the ranking. The sequence data never leaves your machine.
Similar open-source tools#
t3code
Control your coding agents from one interface
Remodex
Control Codex agents from your iPhone, open source and free
Cline
VS Code AI agent that plans and edits across your entire project
Continue
Connect any LLM to VS Code for AI completions and codebase chat
PearAI
Open source AI code editor with chat, autocomplete, and search
OpenCode
OpenCode is an open-source AI coding agent that assists developers in