What the agent does
The agent reads the command line before it touches it, because completion in Click depends on how each parameter is declared. In an app like Textualize/toolong, pyproject.toml is a Poetry project whose only script is tl = "toolong.cli:run", with click, textual and typing-extensions as dependencies and textual-dev for development, and no tests directory. src/toolong/cli.py declares run as a single @click.command() with @click.version_option, an argument files with metavar="FILE1 FILE2" and nargs=-1 and no type, a -m/--merge flag and a -o/--output-merge option whose metavar is PATH. When no files are given on a terminal it prints the help; when stdin is a pipe it copies the input to a temporary file and relaunches sys.argv[0] on that path with TEXTUAL_ALLOW_SIGNALS=1, which the agent notes because any new type on files must accept that path. src/toolong/log_file.py opens each path with open(self.path, "rb", buffering=0) and picks gzip or bz2 by extension, so a directory was never a valid argument. The README says to install with pipx install toolong or pip install toolong, which matters: Click's completion only works for a program installed as an entry point.
Click's documentation says completion covers command names, option names after a dash, Choice values and File and Path parameters, and that an untyped argument completes nothing. So the agent gives files the type click.Path(exists=True, dir_okay=False), which the temporary-file relaunch satisfies and which also turns a mistyped filename into a Click usage error instead of a traceback from open, and gives --output-merge the type click.Path(dir_okay=False, writable=True) so a path completes there too. Then it adds a --completion option taking bash, zsh, fish or powershell through click.Choice, whose callback builds the script with click.shell_completion.get_completion_class(shell)(run, {}, "tl", "_TL_COMPLETE").source(), prints it and exits, the same text the _TL_COMPLETE=bash_source tl form produces, so a reader never has to remember the variable. The README gains a section with the one-line setup per shell from Click's documentation, in the saved-script form that avoids running tl on every shell start, and the Fish form that writes to ~/.config/fish/completions/tl.fish.
Tests come with it, since the repository has none and the behaviour is easy to pin. The agent adds pytest to the dev group with poetry add --group dev pytest and writes tests/test_cli.py: CliRunner().invoke(run, ["--completion", "bash"]) exits 0 and the output contains _TL_COMPLETE; click.shell_completion.BashComplete(run, {}, "tl", "_TL_COMPLETE").get_completions([], "") returns one item whose type is file, which is how Click hands path matching to the shell for the files argument; the same call with ["--output-merge"] returns a file item; and get_completions([], "-") lists --merge, --output-merge, --completion, --version and --help. A last test passes a path that does not exist and checks the usage error names FILE1 FILE2.
Then it proves it in a shell. The agent installs the package into a virtual environment with pip install -e ., so tl exists on the path, runs tl --completion bash into a file, sources it in a fresh bash with a scratch directory of .log and .log.gz files, and drives completion through compgen-style invocations of the generated function to show the filenames come back, then repeats the check in zsh with the zsh script. It runs tl --version and tl with no arguments to confirm the help still prints, and printf 'a\nb\n' | tl to confirm the piped path still relaunches with the temporary file under the new type.
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 Textual app's command line. Read pyproject.toml, the cli module, the module that opens log files, the README's install section and any existing tests first. Give the file argument and the output path option Click Path types so they complete filenames, keeping the piped-stdin path that relaunches the command on a temporary file working. Add a --completion option with a Choice of bash, zsh, fish and powershell that prints Click's completion script for the installed command name, and document the per-shell setup in the README in the saved-script form. Add pytest to the dev dependencies and write tests for the script output, the completion items of the file argument and option, and the option names. Install the package into a virtual environment, generate the bash and zsh scripts, source each in a fresh shell over a directory of sample log files and show the completions, and open a pull request linked to the issue 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 changes src/toolong/cli.py, pyproject.toml and poetry.lock, and adds tests/test_cli.py and a README section. Its description quotes the pytest run, the bash and zsh completion output over the sample directory, the unchanged help text, and the piped-stdin check.
A reviewer checks whether exists=True is too strict for a workflow that opens a log before it is written, which the pull request raises as a question with exists=False as the one-word alternative, and whether the README should also show the PowerShell form. After merging, a user who installed with pipx runs one command per shell and gets filenames after tl.
Run it on every Linear issue labelled cli
An automation in the Project that holds the app takes a linear trigger on linear.issue.labeled with the label cli. Its runs are read-only, so the saved prompt asks for a plan: the run reads the command, lists the parameters that would gain types and the shells it would document, and posts that as a comment on the issue, where a maintainer can say whether the file argument may name a file that does not exist yet. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to resources and a request_id that is a UUID v5 of the issue id, so a retried start returns the run already started.
A team that ships several terminal apps sends one request per repository, each with its own resources entry; an app whose entry point is a click.Group gets a completion subcommand instead of an option, because that is where its users look.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Completion is cheap to add and easy to get subtly wrong: an argument without a type completes nothing, a type that is too strict breaks the piped-stdin path the app relies on, and a script generated under the wrong program name never loads. The agent reads the entry point and the relaunch code, installs the package the way users do, and exercises the generated scripts in real shells in its own sandbox, keeping every command and its output in the run's record.
It also leaves tests behind in a repository that had none, so the next change to the command line keeps the completion honest. Several terminal apps get the same treatment at once, each with the setup lines for its own command name.
Frequently asked questions
Why add a --completion flag when Click already has the environment variable?
Both produce the same script; the flag is discoverable in --help and spares users the _TL_COMPLETE=bash_source tl spelling. The agent builds it with Click's own get_completion_class, so there is no second implementation to keep in step.
Does completion work when the app is run with python -m?
No. Click's documentation says completion needs the program installed as an entry point and invoked by its name, which is how pipx install toolong sets it up. The README section says so, and the tests exercise the script through CliRunner rather than the shell for that reason.
Will the Path type break reading from a pipe?
No. The piped path writes stdin to a temporary file and relaunches the command on that file's name, which exists, so click.Path(exists=True) accepts it; the agent runs that case and quotes it. A directory was never a valid argument because the file opener reads bytes from the path.
What about Windows users?
Click generates a PowerShell script too, and the --completion choice includes it, but the agent tests bash and zsh in the sandbox and says so; the README shows the PowerShell profile line from Click's documentation without claiming it was run.