What the agent does
The agent first works out how much completion the command already has, because with Click the answer is most of it. In a CLI like simonw/files-to-prompt, pyproject.toml installs the script files-to-prompt from files_to_prompt.cli:cli, a single @click.command() with one argument, ten options and --version. Click checks an environment variable before the command body runs, named after the program with dashes turned to underscores, here _FILES_TO_PROMPT_COMPLETE. Setting it to bash_source, zsh_source or fish_source prints a completion script for that shell. Nothing in the repository mentions this, so users have no way to know it is there. The README documents the options and says nothing about tab completion.
Then it reads each parameter for what the shell can offer. Option names such as --include-hidden, --ignore-gitignore, --cxml, --markdown and --line-numbers complete without any code. The paths argument is click.Path(exists=True) and -o/--output is click.Path(writable=True), and Click's Path type tells the shell to complete file names, so those work too. Two options take free text. -e/--extension is declared with multiple=True and no type, so a user gets nothing after it; the agent gives it a shell_complete callback that offers the extensions of files under the paths already typed on the command line, falling back to the current directory. --ignore takes glob patterns, where a suggestion would be a guess, so it is left alone and the pull request says why.
Because the callback uses an API from Click 8.0, the agent checks what the project allows. pyproject.toml lists click with no floor, so it adds click>=8.0 and says so, and it keeps the callback free of any import that would slow start-up, since completion runs the program on every press of the tab key. It writes a README section with one line per shell: an eval of the generated script for bash and zsh, a file under ~/.config/fish/completions/ for fish, and a note that saving the script to a file once is faster than evaluating it at every shell start. It adds that Click's bash support needs bash 4.4 or later, which matters on macOS where the system bash is older.
It tests at two levels. In tests/test_files_to_prompt.py, beside the existing CliRunner tests, it adds cases that ask Click's ShellComplete class for completions of a partial option name, of a value after -e in a temporary directory holding .py and .md files, and of a path. Then it installs the package in the sandbox, generates the bash, zsh and fish scripts, checks each one names the program, sources them in real shells, installing zsh and fish first if they are missing, and records what each shell offers for files-to-prompt --inc, for -e and for a path prefix.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add shell completion to this Click CLI. Read pyproject.toml for the click requirement and the console script name, the CLI module, the tests and the README first. List every argument and option with what a shell could complete for it: option names, file or directory paths from click.Path, fixed choices, or free text. Do not write a completion script by hand; use Click's built-in support, where the variable _PROGNAME_COMPLETE set to bash_source, zsh_source or fish_source prints the script. Add a shell_complete callback only to options that take free text and have a sensible set of values, such as file extensions found under the paths already on the command line; leave options alone where a suggestion would be a guess, and say which. Keep the callback fast and free of heavy imports. If the callback API needs a newer Click than the project allows, add the minimum floor and say so. Add a README section with the one-line setup for bash, zsh and fish, the faster save-to-file form, and the bash version Click requires. Add tests that call click.shell_completion.ShellComplete for a partial option, an option value and a path. Then install the package, generate all three scripts, install zsh and fish if missing, source each script in its shell, and record the completions offered for a partial option name, the value option and a path prefix, and time one completion of the value option. Run the full test suite and open a pull request with the commands and their output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request touches four files. files_to_prompt/cli.py gains one short function and a shell_complete= argument on the extension option. pyproject.toml gains the Click floor. The test file gains the completion cases, and the README gains the section on enabling completion. No completion script is committed, because Click generates it from the installed command and a committed copy would go stale with the next option added.
The description quotes the generated script's first lines for each shell, the completions each real shell offered for the three probes, and the full pytest output. It lists every parameter with the kind of completion it gets and the ones deliberately left without. A reviewer tries the one-line setup in their own shell, checks that completing -e in a large directory does not stall, since the callback walks the paths on every tab press, and confirms that running the command normally produces exactly what it did before. The diff adds no branch to the command body, which makes that last check quick.
Run it on every terminal hand-off
This is a job to hand off in the middle of other work. With the Rush MCP server added to the coding agent in your terminal, at https://api.phoenix.so/mcp with your API key, you ask it to start this request on the repository you are in. It calls create_session and returns at once, the run goes on in its own cloud sandbox, and wait_for_sessions or the session read gives you the pull request link when it is ready. Nothing runs on your machine, so your working tree and your shell configuration are not touched.
If you maintain several Click tools, send the same body once per repository from a script, each with a request_id that is a UUID v5 of the repository's full name so a second send returns the run already started. A webhook set on the API key reports each finished run, and each one reads its own options: a command group gets completion for its subcommands with no extra code, and a tool whose options use click.Choice needs no callback at all.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Completion is only real when a shell does it. A unit test can show that Click returns the right items, and that still leaves the generated script, the shell's own quoting and the version of bash on the machine untested. Checking three shells means having three shells, and most people have one. The agent's sandbox installs the missing ones, sources each script and records what the shell offers, and all of it stays in the run's record for the pull request to quote.
It is also a task that is easy to overbuild. A hand-written script, a new subcommand to print it, or a dependency for something Click already does each add a thing to maintain. The agent starts from what the framework provides, adds code only for the one option that needs it, and writes down what it chose not to complete. That keeps the diff to a size someone will read between other tasks, which is the whole point of handing it off.
Frequently asked questions
Do I need a plugin or an extra package?
No. The completion system used here has been part of Click itself since 8.0. The command already answers the _FILES_TO_PROMPT_COMPLETE variable; the pull request documents it and adds value completion for one option.
Which shells does it cover?
Bash, zsh and fish are tested in the sandbox and documented in the README. Bash needs version 4.4 or later for Click's script. The current Click release also has a PowerShell completion class; the agent mentions it and does not test it, since the sandbox is Linux.
Will completion slow my command down?
Normal runs are unaffected: Click checks one environment variable and continues. During completion the program starts once per tab press, so the agent keeps the callback small and reports how long a completion of the extension option takes in the sandbox on the repository itself.
What about a CLI with subcommands?
A click.Group completes its subcommand names and each subcommand's options the same way, with no code. The agent still reads each subcommand's parameters and adds callbacks where a free-text option has an obvious set of values.