warp_completer crate — that runs entirely within the Warp process and provides rich, context-aware suggestions as you type. Unlike traditional shell completions that rely solely on the shell’s built-in complete or compgen mechanisms, Warp’s engine parses the command line token by token, resolves argument types, and surfaces completions with inline descriptions so you can understand each option before accepting it.
How the completion engine works
When you start typing in Warp’s input area, thewarp_completer engine:
- Tokenizes the buffer text into a sequence of
LiteCommandandParsedTokenDataobjects, tracking each token’s position (span), its index within the command, and its type. - Describes each token using the
describefunction, which matches the token against a completion spec to determine what kind of value is expected (a subcommand, a flag, a file path, a custom enum, etc.). - Generates suggestions by calling the
suggestionsfunction with the currentCompletionContext. Suggestions are ranked by aPriorityscore and may be matched using exact, prefix, or fuzzy strategies. - Displays results inline as you type (autosuggestions) and in a pop-up list when you press
Tab.
ParsedTokensSnapshot) is cached between keystrokes so that re-parsing only happens when the buffer actually changes.
Completion specs
Warp uses completion specs — structured definitions that describe a command’s subcommands, flags, and arguments. These specs power the detailed inline descriptions you see next to each suggestion (for example,--verbose: Enable verbose output).
Warp’s completion specs are partly derived from the community-maintained Fig completion specs library (acknowledged as an open-source dependency) and partly from Warp’s own spec format. The v2 completions feature flag enables the next-generation spec engine that supports JavaScript-executed generators for dynamic completions.
The
v2 completion engine (feature flag v2) supports JsExecutionContext and JsExecutionError, which allow spec authors to write JavaScript generator functions that produce completions dynamically at runtime — for example, by reading the output of a command or querying an API.Tab completions
PressTab in the input area to request completions for the current token. Warp opens a completion pop-up that shows:
- Matching suggestions ranked by relevance.
- Type labels — whether the suggestion is a subcommand, flag, file path, or other type.
- Inline descriptions from the completion spec (where available).
Tab/Shift+Tab to move through suggestions, and press Enter or Space to accept the highlighted item.
Autosuggestions
As you type, Warp shows a ghost text autosuggestion to the right of your cursor. The suggestion is drawn from:- Your command history — the most recent matching command is shown first.
- Completion specs — if the spec defines a default or most-likely next token, Warp may suggest it inline.
→) or End to accept the full autosuggestion. Press Ctrl+→ (or Option+→ on macOS) to accept one word at a time.
How Warp completions differ from traditional shells
| Feature | Traditional shell | Warp |
|---|---|---|
| Completion UI | Plain list in the terminal stream | Pop-up with type labels and descriptions |
| Argument descriptions | Not shown | Shown inline from completion specs |
| History-based suggestions | Partial (fish, zsh-autosuggestions plugin) | Built in, no plugin required |
| Dynamic generators | Shell functions only | JavaScript generators (v2) |
| Cross-session history | Shell-dependent | Stored in Warp’s SQLite history database |
| Spec source | Shell built-ins + manual setup | Fig-compatible specs + Warp’s own specs |
Completion matching strategies
Warp supports multiple match strategies, selectable per completion context:Prefix matching
Prefix matching
The suggestion starts with the characters you have typed. This is the most predictable mode and is used for flag names and subcommands where exact spelling matters.
Fuzzy matching
Fuzzy matching
Characters you type are matched anywhere in the suggestion, in order but not necessarily consecutively. Fuzzy matching is useful for long flag names or file paths where you know a distinctive substring.
Exact matching
Exact matching
The suggestion must match your input exactly (case-sensitive or case-insensitive depending on the
TopLevelCommandCaseSensitivity setting). Used for commands where partial matches would be ambiguous.File and path completions
When the current token is expected to be a file path, Warp’sengine module walks the file system using EngineDirEntry and EngineFileType to list files and directories. The path separator is resolved via PathSeparators::for_os(), so completions work correctly on both POSIX systems (forward slash) and Windows (backslash).
Alias completions
If you have defined shell aliases, Warp resolves them during completion. Thesuggest::alias module expands aliases so that completions for the underlying command are available even when you type the alias name.