[idea] Add ZSH Completion

[Jelloeater]

idea / problem

It would be great for herdr to support zsh shell completions in addition to its existing terminal-focused UX.

Motivation

Since herdr is a terminal-native tool, shell completion would make common workflows faster and more discoverable. Zsh completion in particular would help users:

• discover commands and flags without leaving the terminal
• reduce typing for frequently used commands
• avoid errors from misspelled subcommands or options
• make onboarding smoother for new users

This feels especially valuable for a tool aimed at AI coding workflows, where fast iteration in-terminal matters.

requested change

Proposed behavior

Add first-class support for generating or installing zsh completions for the herdr CLI.

Possible approaches:

• provide a command such as herdr completions zsh
• or provide herdr completion zsh
• document how users can install the generated completion script into their zsh setup

If the CLI already uses a framework that can emit shell completions, this may be relatively straightforward to add.

Expected completion scope

Ideally completions would cover:

• top-level commands
• subcommands
• flags and options
• enum-like argument values where applicable
• help-related commands/options

If practical, it would also be nice to support completion for any aliases.

Docs

If implemented, it would help to add unreleased docs in the preview docs area describing:

• how to generate the zsh completion script
• how to install it in zsh
• any differences between temporary/manual install and persistent install

why you want this

This seems aligned with herdr’s terminal-first workflow and should improve usability without changing core behavior.

[Jelloeater]

Just mentioning it because https://github.com/asheshgoplani/agent-deck also has this as well <3

[ggallovalle]

For anyone instered I have a working solution for this, I write my own completions with the usage spec from mise since they are really hard to write on my own

This is the usage spec https://usage.jdx.dev/spec/reference/

This is the usage spec for herdr that I use on my own dotfiles

https://github.com/ggallovalle/dots/blob/main/home/dot_config/zsh/usage/herdr.kdl

And this is how you generate them

# just make sure that file is on zsh fpath
usage generate completion zsh "herdr" -f "<path to the usage file>" > _herdr

It completes dynamic arguments and all, see

$DOTFILES
❯ herdr session attach dots[tab]
default  -- default is stopped (default)
dots     -- dots is running
kbarr    -- kbarr is stopped
kbmedia  -- kbmedia is stopped
kbstd    -- kbstd is stopped
p.kbstd  -- p.kbstd is running
thinker  -- thinker is stopped

$DOTFILES
❯ herdr pane close w6521ff921a4101-
w6521ff921a4101-1  -- w6521ff921a4101-1 is unknown
w6521ff921a4101-2  -- w6521ff921a4101-2 is unknown
w6521ff921a4101-3  -- w6521ff921a4101-3 is unknown

I have a skill to generate it and keep it uptodate, I did not handrite anything at all
The only downside is dependency with the usage cli
https://github.com/ggallovalle/dots/blob/main/home/dot_agents/skills/write-usage/SKILL.md

[lachieh]

This is awesome, thanks @ggallovalle. It looks like herdr uses ratatui which doesn't have support for usage just yet.

In the mean time, I pulled in your .kdl so that it works with mise via a plugin if you have the usage cli installed:

mise plugin install herdr https://github.com/lachieh/vfox-herdr
mise use -g herdr@latest

[Golden-Pigeon]

maybe we could use clap to reimplement the command line args parser (currently it manually parse strings) and then auto generate a completion script.

[ogulcancelik]

#899

moved to issue tracking phase