PSCompletions: one completion engine for PowerShell and other shells

One engine, many shells

The pitch is two clauses: powerful shell completions for PowerShell and other shells, powered by Rust and Lua. The first clause states the ambition, and the second states the unusual part of it.

The idea is that a completion engine is a hard thing to write well and a thing most people have to write twice if they work in two shells. PowerShell has its own completion model, built on a readline library, and every other shell has a different one, with a different plugin protocol, a different way of describing a command, and a different menu. A tool that implements the engine once and speaks each shell's protocol is therefore worth building, and the documentation has a page devoted to the shells it supports.

The Rust and Lua split is the implementation strategy. Rust is a good language for the part that has to be fast and that has to be dependable: parsing a command line, matching a prefix against a catalogue, ranking the results. Lua is a good language for the part that has to be extensible: adding a completion for a new command is a small script, and the repository layout reflects that with separate directories for the engine, for the completions, and for the types they use.

The feature list in the readme is five items and each one is a link to a documentation page, which is a good sign about the depth of the thing.

The first is one engine, many shells. The second is the built-in completion library, whose size is advertised in the header as a badge that reads a count out of a JSON document and updates itself, so the number in the readme is always the number of completions currently shipped. That badge is a nice piece of engineering on its own: the readme pulls the count from the repository's own data file rather than from a number somebody has to remember to update.

The third is a more powerful completion menu. The fourth is multilingual support, with English and Chinese named among them. The fifth is dynamic sorting of completion items based on command history, which is the one that changes behaviour rather than adding a feature, and it is worth thinking about on its own.

The project is MIT licensed, the site is pscompletions.abgox.com, and the last push was on 2026-10-20. The repository is also mirrored to two Chinese forges, which alongside the Chinese readme tells you where a large part of the audience is.

The four install routes, and the two-step setup

The getting started section is short and structured as three steps: install it, load it, use it. The fact that loading is a separate step tells you that this is not a single thing but a set of pieces that have to be wired into your shell.

For PowerShell, the install is the module from the package gallery.

Install-Module PSCompletions # Install-PSResource PSCompletions

The comment gives the alternative spelling, because the gallery and the newer resource manager are two different commands and the project supports both.

For bash, zsh, and fish, the install is a script, and the install method is the one every shell user has seen a thousand times.

curl -fsSL https://raw.githubusercontent.com/abgox/PSCompletions/main/install.sh | sh

The third route is a package manager for Windows, and again the command has a comment with the alternative.

scoop install pscompletions # scoop install abyss/abgox.PSCompletions

That the script is piped straight into a shell is worth a moment's thought, because it is the pattern security guides dislike, and the alternative would be a download followed by a manual run. The project is a small tool with a single maintainer, and the trade is convenience against reviewability, and the script is short enough to read before running it if you want to.

Then there is the loading step, and for PowerShell it is a module import.

Import-Module PSCompletions

The documentation links a page on importing the module directly for that case, and for the other shells the install script tells you how to load it, which is the right division of labour: the script knows the three different shell startup files and the module does not.

And then the use step, which is a command.

psc

and one that adds a completion.

psc add git

So the tool has a command of its own, not just a shell integration, and that command manages the completion library. The add subcommand is what you reach for when a program you use is not in the shipped set, and it is the visible face of a design where the completions are data the user can extend.

The completion library, and what a completion actually is

The built-in completion library is the substance of the project, and the readme treats it as a first class feature with its own documentation page and its own file in the repository.

The file is a JSON document, and the badge in the readme is a dynamic image that reads a count out of it. That means the catalogue is data, in a format a program can read and a person can inspect, and it means the number of completions is a fact about the data rather than a claim in the prose.

What a completion is in this system is not stated in the readme, so it is worth inferring from the surrounding structure rather than inventing. The repository has a completions directory and a types directory and a schema directory, and the type of thing being described is a command: its subcommands, its flags, what each flag takes, and what it means. A completion for a version control system therefore has a set of subcommands with their own options, and the completion engine can offer them once you have typed the subcommand name.

The schema directory is the reason this can work across four shells. If each shell described completions differently, the library would need four versions of every entry. With one schema and a per-shell adapter, an entry is written once.

The types directory is what makes the entries typed rather than a bag of strings. A completion that knows whether a flag takes a value, whether the value is a path, and whether an argument is optional can be filtered and validated by the engine, and can be rendered differently in the menu, for example showing a path flag with a marker so the completion can be completed with a filesystem browse.

So the architecture is: a data catalogue of typed command descriptions, a schema and a type system to constrain it, a Rust engine that reads the catalogue and produces candidates, and a Lua layer for the parts that are naturally scriptable, plus one adapter per shell.

And the add command fits that architecture. If a completion is data, then adding one is adding an entry, which is why the command is a first class part of the interface rather than a maintenance script buried in the repository.

The menu, the languages, and the history based sorting

Three of the documented features are about what happens once you have a list of candidates, and they are worth separating because they solve different problems.

The completion menu is the first. The readme's acknowledgements name the inspirations, and they are the two projects whose interaction design the menu borrows from: fzf and its PowerShell port, for the completion menu. fzf's contribution to the command line is the idea that a fuzzy finder can be a general purpose selection interface, and that the quality of the matching matters more than the speed of the matching.

For a completion menu, the obvious alternative is the shell's own list, printed in a column. The difference between a column of names and a fuzzy finder is that the finder lets you type a few characters that are not a prefix and still find the thing you meant. A completion list for a system with a hundred commands in it is exactly the case where prefix matching is annoying and substring matching is not.

The second feature is multilingual support, with English and Chinese named. A completion menu is a place where language shows up in an obvious way, because the descriptions are text, and because the sorting and the fuzzy matching have to handle non-ASCII input. If the candidates are Chinese command descriptions and the user types pinyin, the matching has to know about that, and a system built for one language does not.

The third is the one with the strongest claim to being original, and it is the sorting based on command history. A static completion list puts the candidates in a fixed order, usually alphabetical, which means the command you use every day is in the same place as the one you used once. If the engine knows your history, it can put the frequent ones first.

That is a small change with a large effect on the felt speed of completion, and it is the kind of feature that other completion systems have added separately over the years. Doing it inside the engine rather than in the shell integration means the ordering survives the translation between shells, so your history helps you in whichever shell you are in.

The three features together are the argument that the interesting work in a completion system is not in matching but in everything around the matching: how the candidates are presented, how they are filtered, how they are ordered, and in what language the descriptions are written.

The repository, and the directories that describe the design

The top level of the repository is where the design is stated, because the directory names are the modules.

There is a core directory, which is the engine. There is a completions directory, which is the catalogue. There is a types directory and a schema directory, which are the type system and the constraints on the data. There is a module directory, which is the PowerShell module, with its own change log. There is an install script at the root. There is a scripts directory and a design directory and a decisions directory and an authoring directory.

Those last four are the ones that say something about how the project is run. A design directory holds the intended shape, an authoring directory holds the inputs for producing entries, and a decisions directory holds the records of choices that have been made. A project that keeps a decisions directory is one where the reasoning behind a choice is expected to outlive the choice itself, which is what you want when the next person asks why the menu behaves the way it does.

The module directory having its own change log is worth a small note. A PowerShell module published to a package gallery has a version history that users can see, and the project points at that change log from the readme for the details of what is new. So the release history of the tool is published where the people using it will look.

There is a separate Chinese readme, an editor configuration directory, an agent instruction file, and a licence file. The presence of the Chinese readme alongside the English one is a small choice that reflects the audience, and it is consistent with the mirrors to two Chinese forges and with the Chinese as one of the two named interface languages.

And there is a contribution guide in the GitHub directory, which the readme points at, plus an issue and pull request workflow implied by the standard repository layout.

Taken together, the layout suggests a project with a real pipeline: a schema and a type system to define what a completion is, an authoring directory to write them, a catalogue to hold the results, a core to consume them, an adapter set to serve four shells, and a module packaging for the PowerShell case.

What it borrows, and what it is

The acknowledgements section is short and names two projects, and both are worth understanding because they explain the shape of the result.

The first is the PowerShell readline library, credited as the editing and completion foundation for PowerShell. That is the layer that owns the line editor, the history, and the completion request itself, and any tool that wants to improve completion in PowerShell has to work through it rather than replace it. The project's positioning as an addition rather than a replacement follows from that.

The second is the fuzzy finder and its PowerShell port, credited as the inspiration for the completion menu. So the menu is not an original design; it is a known interaction pattern applied to a new context, which is usually the honest and effective way to arrive at a good interface.

The third thing the readme establishes is the licence, the MIT one, and the copyright, which is in the readme rather than only in the licence file.

So the shape of the project is: an engine written in Rust, a scripting layer in Lua, a typed data catalogue of completions, adapters for four shells, a PowerShell module for the platform where the completion protocol is richest, and a menu that borrows the interaction model of a fuzzy finder.

What is notable is the ordering of those choices. Most shell completion work is done in the shell's own plugin language, in Bash, in Zsh script, in Python for the Python library, and each one is a separate implementation. Building the engine once in a compiled language and leaving the shell-specific parts thin is the choice that makes four shells plausible rather than aspirational, and the Lua layer is where the extensibility lives so that adding a completion does not require recompiling anything.

The project is young enough that the changelog and the completion count are better indicators of where it is than any version number would be, and the count is published in the readme as a live number for exactly that reason.

Editorial conclusion

PSCompletions fits a person who lives in more than one shell, or who has moved to PowerShell and wants completion that does not feel like a step backwards. It does not fit a user who is perfectly happy with what their shell already offers, since the payoff comes from the shared library rather than from any single integration. Verify first that the completion library covers the commands you actually use, since the count of shipped completions is the practical measure of how much of your workflow it will handle, that the shell you use is on the supported list, and that the install route you pick matches your system, because the module and the script installers do different things.

Frequently asked questions

Official sources

1. abgox/PSCompletions on GitHub
2. Issues
3. License: MIT
4. Project website
5. README