A shell that writes its own tab completions

Assaf Schwartz — Fri, 31 Jul 2026 17:32:12 +0000

Type this into most shells and watch what happens:

❯ docker rm <TAB>
Dockerfile        docker-compose.yml    docs/

Filenames... docker rm does not take a filename. It takes the name or ID of a container that exists on this machine right now, and the machine knows exactly which ones those are. The shell just has no idea how to ask...

You can fix this yourself, in most shells: a bash function juggling COMP_WORDS and COMPREPLY, a zsh #compdef file in the _arguments DSL, or, closest to easy, a one-line fish complete command. bash-completion is tens of thousands of lines of that fix. At that price, I wouldn't write a completion for an internal CLI at 4pm on a Tuesday.

For Hash, I wanted this to stay easy and hackable: you should be able to teach your shell a new tool yourself, in a minute, without shell scripting and without waiting for me or the tool's author to do it for you. That seemed like the right thing to do.

Thirty seconds, one command

Here is that minute. A real run of completions generate against gh, trimmed; the full output came back with ten rules:

❯ completions generate gh
Inspecting `gh --help`...
Asking the agent to draft a completion plugin for gh...

Generated plugin for gh:

  [plugin]
  name = "gh"
  description = "Complete GitHub resource names for the gh CLI"
  commands = ["gh"]

  [[rules]]
  subcommands = ["pr view", "pr checkout", "pr diff", "pr merge", "pr edit", ...]
  max_args = 1
  [rules.source]
  exec = ["gh", "pr", "list", "--state", "all", "--limit", "100",
          "--json", "number,title", "--jq", ".[] | \"\(.number)\t\(.title)\""]
  delimiter = "\t"
  value_column = 1
  description_column = 2
  timeout = "8s"
  cache_ttl = "30s"

  [[rules]]
  subcommands = ["run view", "run watch", "run rerun", "run cancel", ...]
  max_args = 1
  [rules.source]
  exec = ["gh", "run", "list", "--limit", "100",
          "--json", "databaseId,displayTitle", "--jq", ".[] | \"\(.databaseId)\t\(.displayTitle)\""]
  ...

10 rules covering: pr view, pr checkout, pr diff, ..., issue view, issue close,
repo view, repo clone, release view, run view, workflow run, label edit,
secret delete, variable delete, ...

[a]ccept  [r]evise <what to change>  [q]uit:

The prompt at the bottom is the feature:

[a]ccept when the draft is good enough. Often it is.
[r]evise also cover gists sends your instruction plus the current spec back to the agent. As many rounds as you like.
A draft that fails validation just hides accept and sends the error along with your next instruction. One round usually fixes it.
Unknown fields are hard errors, so a machine-written cache_tt fails loudly while the model is still around to fix it, instead of shipping a plugin that looks correct and behaves wrong.

Accepting writes the file to ~/.config/hash/completions/, hot reloads the plugin table, and makes the completion live in the same shell. No restart.

❯ completions list
Completion plugins:
  docker         docker (built-in, 13 rules)
  gh             gh (user, 10 rules)

User plugins live in ~/.config/hash/completions

From this moment, gh pr checkout <TAB> completes PR numbers with their titles beside them, and gh run watch <TAB> knows your workflow runs.

Edit the file by hand and run completions reload. Regenerate it. Delete it. It's yours from the moment you accept it. That's my gift to you: the agent gets you past the blank page, and then leaves.

That is the whole feature. The rest of this post is what just happened behind the scenes.

Who can tell the shell which containers exist?

Hash already had the first three: tool-native completion for CLIs that ship it (kubectl, gh), hand-written handlers for a deliberate short list, and the ?? agent. Plugins fill the fourth row.

The first three all wait on somebody. Tool-native completion is excellent where it exists, but the tool's author has to have shipped it. Built-in handlers exist because I shipped them, which does not scale beyond my motivation and bandwidth.

The missing tier is for the very large category of tools that have live, queryable state and no completion protocol. Something has to run docker ps. The only question is who declares that, and in what language.

The format is deliberately not a language

The file the agent wrote answers three questions: where it applies, which command produces candidates, and which column contains the value. That reflects the design question, which was never "what can a plugin do?" but "how little can a plugin be allowed to do and still cover the docker rm case?" The result is small enough to skip the agent entirely and write by hand:

# ~/.config/hash/completions/kubectl.toml
[plugin]
name = "kubectl"
commands = ["kubectl", "k"]

[[rules]]
subcommands = ["delete pod", "describe pod", "logs"]
[rules.source]
exec = ["kubectl", "get", "pods", "-o", "custom-columns=NAME:.metadata.name,STATUS:.status.phase", "--no-headers"]
value_column = 1
description_column = 2
cache_ttl = "5s"

That is the whole thing. The exec array is passed directly as argv with no shell interpretation, each output line becomes one candidate, and Hash splits and maps the columns:

Shown with the docker plugin's docker ps source; the kubectl spec above maps the same way. The parser is one function: split the line on the delimiter, take one column as the value and optionally another as the description, drop empties and duplicates. There is very little surface area for bugs.

The interesting part of that format is what it refuses to have. There are no conditionals, no variables, no access to the current word, no way to post-process the source's output. When output needs reshaping, the reshaping goes inside the source command itself. terraform workspace list marks the current workspace with an asterisk, so a workspace plugin strips it there:

[rules.source]
exec = ["sh", "-c", "terraform workspace list | tr -d '* '"]

The pipeline lives in the plugin's own command, rather than in a config language slowly growing into one.

Two constraints do most of the work of keeping it tight.

A matched rule owns the argument. When a rule matches and the source answers with nothing, that's an answer: "no matches." Completion stops there and does not helpfully offer you filenames instead. docker rm with no containers running should give you nothing, because nothing is the truth.

Plugins never complete flags. Type - and the plugin declines and lets a lower tier answer. This one is a scope decision rather than a technical limit: Cobra already completes flags properly for the tools that support it.

The built-in plugin is a plugin

The fastest way to end up with a bad extension format is to ship the "real" implementation in your own language and the extension surface as a lesser thing beside it. The internal path stays expressive, the public one calcifies, and you never feel the difference because you never use it.

So the only third-party completion plugin Hash ships is for Docker, and it is a TOML file. Not a TOML-shaped API. Actual TOML, as a string constant in the binary:

const builtinDockerSpec = `
[plugin]
name = "docker"
description = "Containers, images, volumes, and networks for docker"
commands = ["docker"]
value_flags = ["-c", "--context", "-H", "--host", ...]

[[rules]]
subcommands = ["rm", "inspect", "logs", "container rm", "container inspect", ...]
forward_flags = ["-c", "--context"]
[rules.source]
exec = ["docker", "ps", "-a", "--format", "..."]
delimiter = "\t"
value_column = 1
description_column = 2
timeout = "3s"
cache_ttl = "0s"
...
`

func builtinPluginSpecs() []*PluginSpec {
    return []*PluginSpec{
        mustParsePluginSpec(builtinDockerSpec),
    }
}

That mustParsePluginSpec is the whole point. It runs the same ParsePluginSpec your files go through, including the strict unknown-field check, and it panics on failure. A typo in the built-in spec is a shell that refuses to start, which is exactly the deal I want: if I ever weaken the format, or add a key the parser doesn't accept, I find out immediately rather than shipping an extension surface I never actually use.

It buys real things. Writing those 13 rules kept hitting cases the format could not express, and with no internal escape hatch available, every one of them had to become a format feature that your plugins get too.

And because it is genuinely just a plugin, it has no privileges. Write a docker.toml of your own and yours replaces mine wholesale. Ship one with disabled = true and mine is gone with nothing in its place. The built-in is the reference implementation in the most literal sense: you can read all of it.

Why the agent gets it right

completions generate was not the plan; it showed up later, in the shower, where my best ideas always come. It works because the format is small. TOML-with-no-logic is auditable: you can read a plugin in five seconds and know exactly what will run on your machine. The same property means a language model can draft one reliably, because there is so little program surface to get subtly wrong: a fixed set of keys, a fixed shape, and a validator.

Mechanically, the shell captures the tool's own --help, hands the agent the spec reference plus that help text, and gets back TOML. Everything else in the gh run was inferred. Every source asks for --json plus a --jq template that emits exactly two tab-separated columns, because the prompt prefers machine-readable output over scraping human tables and the model mapped that rule to gh's --jq support. max_args = 1 landed on every rule because gh pr checkout 4821 extra-arg stops being a PR reference after the first positional.

The hard part was latency

The format took an afternoon. The rest of the time went into one mismatch: a completion source is a process, and TAB is a keystroke.

The completion router gets about 150 ms to show something. A cold, busy, or remote docker ps can take longer than that, and both obvious answers are bad: block on it and TAB feels broken; give up at the deadline and the source never finishes, so the plugin never works at all.

The way out is to stop treating the source as part of the keystroke:

The source is launched on a detached context, bounded only by its own timeout, so a UI deadline can never kill it before it fills the cache. The completion that asked gives up after 40 ms; the source does not.

Walk through it from top to bottom. Each piece exists because the naive version failed in a specific way:

Wait 40 ms, then get out of the way. A cold source gets 40 ms of the shared 150 ms budget; past that, Hash shows a dim fetching completions... and lets the detached process run.

Conceding is not failing. Giving up waiting returns a distinct Pending result: this argument is mine, the data is in flight, nobody else answers for it. Without that, a slow docker ps degrades into filenames.

The menu fills itself in. When the source lands, a callback re-runs the completion and opens the menu. No second TAB, and that detail is the difference between a thing you use and a thing you remember exists.

Stale beats empty. Past cache_ttl, the old output is still served for up to a minute while a refresh runs in the background. So cache_ttl controls how fresh the data is, not whether TAB feels responsive.

Failure has to be remembered. This was the good bug: with Docker down, the failure callback woke the editor, which retried, which relaunched the failing source, forever. A negative cache remembers a failure for 5 s and breaks the loop.

The cache key includes the working directory. gh pr list answers differently in every repository; after a cd, the wrong project's answers are worse than none.

The one place this design fights itself is freshness: run docker stop web-server, then docker rm <TAB>, and a cache doing its job shows the state from before your own command. That is what cache_ttl = "0s" is for. Caching is right by default and wrong precisely where you are the one mutating the state.

What it won't do

The limits matter. A feature described only by its happy path is marketing.

The quality of a generated spec is only as good as the tool's --help. Tools with poor help produce thin plugins, and the agent is instructed not to invent subcommands it cannot see, so the failure mode is a plugin that covers less than you hoped rather than one that invents commands. Sources must be read-only, non-interactive, and bounded: Hash may run them during completion, in their own process group, with stdin from /dev/null. A failed source stays silent and falls through to the next tier, so a broken plugin looks like no plugin.

Concluding

The feature is a TOML file and a subprocess. The idea is that extensibility only counts if the cost of extending is lower than the cost of tolerating the gap.

For thirty years, teaching a shell about your tools has meant writing shell scripts, and nearly every developer has decided that tolerating filenames where container names should be is cheaper. Dropping the price to twelve lines of TOML changes that math. Dropping it to one command, with a model doing the typing and a validator holding the line, changes it again.

Completion plugins land in the next Hash release. The docs are here, the built-in docker spec is the reference implementation, and if completions generate writes something wrong for a tool you use, that's a bug I want to see.

Originally published at goldenhex.dev.

DEV Community: Assaf Schwartz