Completion System

Fast, smart, extensible. No shell scripting required.

Multi-tier architecture

Hash tries completers in priority order and the first one that owns the argument wins:

A tier that matches the argument owns it, even while its data is still loading. If a plugin source is slow (a cold docker daemon, say), Hash shows a dim fetching completions... notice and opens the menu by itself when the data lands, instead of offering filenames that would be wrong for that argument.

The menu is searchable: keep typing while it is open and the list narrows with each character (using your configured matching mode, prefix or fuzzy); backspace widens it again. Hash's own builtins complete too: builtin names appear in command position labeled hash builtin, and completions <TAB> offers its subcommands.

Completion plugins

Plugins teach the shell where completion candidates for a command come from. A plugin is a small TOML file: it declares a command to run and how to parse its output into completion items. Hash ships with a built-in plugin for docker:

The docker plugin knows which subcommand wants which list: docker stop completes running containers, docker start completes stopped ones, docker rmi completes images, and so on. Its sources run with no cache, so completion state always reflects the command you just ran.

Generate one with the agent

The fastest way to write a plugin is to let the shell's agent do it:

Revise as many times as you like; each round sends your instruction back to the agent. Accepting writes the spec to ~/.config/hash/completions/kubectl.toml and activates it immediately, no restart.

Or write one by hand

Rules map subcommands to a candidate-producing command; one output line becomes one completion item. Sources run isolated and off the keystroke path: results are cached per command and working directory, slow sources fill in via the fetching notice, and a user spec that declares docker replaces the built-in one. The full spec reference lives in completion-plugins.md.

Aliases and functions

Hash completes your user-defined aliases and shell functions. These show with a ƒ icon to distinguish them from PATH executables.

• Aliases defined with alias name='...'
• Functions defined with name() { ... }
• Functions from sourced scripts (~/.hashrc)
• Functions imported during shell migration

Alias/function completions work anywhere in the command line, not just at the start. This is useful for commands like xargs or find -exec that take function names as arguments.

File completion details

• Tilde expansion: ~/ → home directory
• Hidden files: shown if prefix starts with .
• Directory indicator: / appended
• Preserves ./ prefix (e.g., ./src<TAB> → ./src/)

Fuzzy matching

When enabled, completion items are fuzzy-filtered by subsequence matching:

• idx matches index.js, index.html
• mnts matches main_test.go

Icons

File type icons (requires Nerd Font):

• .go → Go gopher
• .py → Python
• .js/.ts → JavaScript/TypeScript
• Directories → folder icon