What the agent does
The agent reads the app's actions before exposing them. In an app laid out like Textualize/toolong, pyproject.toml pins textual ^0.58.0 (0.58.0 in poetry.lock) and click ^8.1.7 under Poetry, with tl = "toolong.cli:run" as the entry point and textual-dev in the dev group; there is no test suite and no CI. src/toolong/ui.py defines UI(App), which pushes a LogScreen whose only binding is f1 for action_help, and the screen composes one LogView per file inside a TabbedContent. src/toolong/log_view.py holds the bindings a user actually reaches for: ctrl+t for action_toggle_tail, ctrl+l for toggle('show_line_numbers'), ctrl+f and / for action_show_find_dialog, and ctrl+g for action_goto. src/toolong/log_lines.py adds m, o and d (and their uppercase forms) for action_navigate by minute, hour or day, and src/toolong/help.py renders the key list as Markdown in a HelpScreen.
Textual 0.58 already has the palette; the app just has nothing in it. App.ENABLE_COMMAND_PALETTE defaults to True, App.COMMANDS is a set holding the system commands (toggle dark mode, quit, ring the bell), and the app-level binding ctrl+backslash runs action_command_palette. A provider is a subclass of textual.command.Provider with an async def search(self, query) that yields Hit objects: a score and a highlighted display from self.matcher(query).match(name), a callable to run, and optional help text. An optional async def discover(self) yields DiscoveryHit rows shown before the user types. The provider sees self.app, self.screen and self.focused, which is how it reaches the active LogView.
The agent adds src/toolong/commands.py with a LogCommands(Provider). Its command table maps names to the existing actions on the active screen: Toggle tail, Toggle line numbers, Find, Go to line, Help, and Forward and Back one minute, hour and day, each resolved at run time by querying the focused tab's LogView and LogLines rather than holding a reference, because the screen can switch tabs. search runs the fuzzy matcher over the table and yields a Hit per match; discover yields the same rows so the palette is useful when opened empty. Then UI.COMMANDS = App.COMMANDS | {LogCommands} in ui.py, which keeps the system commands and adds the app's. The HELP_MD string in help.py gets one line naming ctrl+\ so the palette is discoverable from the help the app already has.
There is no test runner in the repository, so the agent adds a minimal tests/test_commands.py using pytest and Textual's App.run_test() pilot, which exists in 0.58: it starts the app on a temporary log file, presses ctrl+backslash, types part of a command name and asserts the palette lists it, then selects it and asserts the LogView's tail reactive flipped. pytest and pytest-asyncio go in the Poetry dev group, and poetry run pytest in the sandbox is the output the pull request quotes. The textual-dev console can show the same thing by hand, which the description mentions for anyone reviewing on a laptop.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add command palette commands to this Textual app. Read pyproject.toml, poetry.lock, src/toolong/ui.py, log_view.py, log_lines.py, help.py, find_dialog.py and goto_screen.py first, and check the pinned Textual version so you use that version's command palette API. Add src/toolong/commands.py with a Provider subclass whose search method yields a Hit for each matching command and whose discover method lists them all: toggle tail, toggle line numbers, find, go to line, help, and forward and back by one minute, hour and day, each resolved at run time against the LogView in the active tab. Register it by setting UI.COMMANDS to App.COMMANDS plus the new provider so the system commands stay. Add the ctrl+backslash key to the help text. Add a pytest test using App.run_test that opens the palette, searches for the tail command, runs it and asserts the LogView's tail reactive changed, with pytest and pytest-asyncio in the Poetry dev group. Run poetry install and poetry run pytest and open a pull request that quotes the output and lists each command with the action it calls.",
"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 adds src/toolong/commands.py and tests/test_commands.py, changes src/toolong/ui.py (the COMMANDS class variable and an import), src/toolong/help.py (one line), and pyproject.toml and poetry.lock (the two test packages in the dev group). Its description lists each palette command next to the action and binding it mirrors, quotes the poetry run pytest output, and names the Textual version the provider was written against.
A reviewer checks that the provider resolves the LogView at run time rather than capturing one at construction, so switching tabs in a multi-file session runs the command on the visible file, that the system commands are still present, and that no new binding shadows an existing key. They may want fewer navigation commands in the palette, which is a matter of deleting rows from the table.
After merge, ctrl+\ opens a searchable list of everything the app can do, each row running the same action a key would, with the keys still working as before.
Run it on every Dependabot pull request that bumps Textual
The command palette API has moved between Textual releases, so the useful event is a version bump. An automation on the Project with a github trigger on pull_request.opened filtered to Dependabot's login in authors runs on each bump, installs the new version in its sandbox, runs the palette test and posts a review comment with the result and any renamed symbol it found in the release notes. An automation's run is read-only, so it comments and pushes nothing.
When the comment reports a break, a handler on the reader's own server starts the fixing run by sending this body to POST /o/{org}/sessions with the pull request URL in resources and a request_id that is a UUID v5 of the pull request's head commit SHA, so a retried delivery returns the run already started. That run updates the provider for the new API and pushes to the bump branch.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The palette API is small but version-bound, and an app with no tests gives no signal when it drifts. The agent reads the pinned version, writes the provider against that API, and adds the first test the repository has, running it in a sandbox where the terminal app can be driven by a pilot and the output is kept with the pull request.
A team with several Textual tools runs the same change on each, and each run reads its own bindings. The provider for a log viewer exposes tailing and time navigation; the one for a different app exposes whatever its screens define, because the agent built the table from the code rather than from a template.
Frequently asked questions
Which key opens the palette?
In Textual 0.58 the app-level binding is ctrl+backslash, bound to action_command_palette with ENABLE_COMMAND_PALETTE on by default. The agent adds that key to the help screen so users find it; newer Textual releases may bind a different key, which the version-bump automation would report.
Do the existing keyboard shortcuts still work?
Yes. The provider calls the same action methods the bindings call, action_toggle_tail, action_show_find_dialog, action_goto and action_navigate, so the palette is a second way in rather than a replacement, and no binding is changed.
Why keep the system commands?
Because App.COMMANDS holds Textual's own provider for toggling dark mode, quitting and ringing the bell. Setting COMMANDS to a union with the new provider keeps those; replacing the set would silently remove them.
How is a terminal app tested in CI?
With App.run_test(), which runs the app headless and returns a pilot that can press keys and wait for the screen to settle. The test the agent adds presses the palette key, types, selects a command and asserts a reactive attribute changed, all without a real terminal.