What the agent does
The agent reads how the app is started before it adds a file that changes that. In an app laid out like Textualize/toolong, pyproject.toml is a Poetry project at version 1.5.0 for Python ^3.8, depending on click ^8.1.7 and textual ^0.58.0, with textual-dev in the dev group and one script, tl = toolong.cli:run. cli.py is a click.command taking FILE1 FILE2 arguments, -m/--merge and -o/--output-merge PATH; with no files on a terminal it prints the help, and with piped input it copies stdin to a temporary file and relaunches itself in a child process. ui.py defines UI(App), which takes file_paths, merge and save_merge, and LogScreen, which opens one tab per file or a merged tab. log_view.py holds the per-file state as reactives: show_line_numbers (off), tail and can_tail, bound to ctrl+l and ctrl+t; find_dialog.py has Case sensitive and Regex checkboxes; help.py renders a Markdown help screen. There is no tests directory, no configuration and nothing persists between runs.
It adds src/toolong/config.py: a Config dataclass with merge, show_line_numbers, tail, find_regex and find_case_sensitive, all defaulting to today's behaviour, and a load() that reads config.toml from platformdirs.user_config_dir("toolong"), which is ~/.config/toolong on Linux, with TOOLONG_CONFIG as an override for a different path. Python 3.11 ships tomllib; for the 3.8 to 3.10 range the project supports, tomli is added with a python = "<3.11" marker alongside platformdirs in the Poetry dependencies. A missing file means defaults. A file that does not parse prints one line to stderr naming the path and the error and continues with defaults, and an unknown key is reported the same way rather than ignored, since a typo in a config file is otherwise invisible.
The precedence is flag, then file, then built-in. cli.py changes its two options to default to None, adds --config PATH and --init-config, which writes a commented template to the config path and exits, and passes a Config into UI. UI hands it to LogScreen, which sets show_line_numbers and tail on each LogView it creates (tail only where can_tail holds, which merged views never do), and FindDialog reads the two find defaults when it mounts. The help screen in help.py gains a Configuration section listing the keys and the path, and the README gets the same.
Tests are new to the project, so the agent adds pytest and pytest-asyncio to the dev group and a tests/ directory: test_config.py loads from a tmp_path, checks the env override, the unknown-key warning and the bad-file fallback; test_ui.py uses Textual's App.run_test() pilot to start UI on a temporary log file with show_line_numbers = true and asserts the LogView reactive is on, then presses ctrl+l and asserts it turns off, which proves the file sets the starting state without taking over the binding. poetry run pytest passes before the pull request opens.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a TOML config file to this Textual app. Read pyproject.toml, src/toolong/cli.py, src/toolong/ui.py, src/toolong/log_view.py, src/toolong/find_dialog.py, src/toolong/help.py and the README first. Add src/toolong/config.py with a Config dataclass for merge, show_line_numbers, tail, find_regex and find_case_sensitive, loaded from config.toml under platformdirs.user_config_dir for toolong or the path in TOOLONG_CONFIG, using tomllib on 3.11+ and tomli below. Report an unparseable file or an unknown key on stderr and fall back to defaults. Make the CLI flags default to None so a flag beats the file and the file beats the built-in default, add --config PATH and --init-config, and pass the Config into UI so LogView and FindDialog start with its values. Document the keys in help.py and the README. Add pytest with tests for loading, the env override, the warnings, and a run_test pilot that starts the app with show_line_numbers on and toggles it. Run poetry run pytest and open a pull request that shows the template file --init-config writes.",
"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/config.py, tests/test_config.py and tests/test_ui.py, changes cli.py, ui.py, log_view.py, find_dialog.py, help.py, the README and pyproject.toml (two runtime dependencies, two dev dependencies, the lock file). Its description shows the template --init-config writes, the precedence rule in one sentence, and the pytest output.
A reviewer runs tl --init-config, edits the file, starts the app on a log and watches line numbers come up without the flag, then passes --merge on the command line against a file that says merge = false to confirm the flag wins. They read config.py for what happens on a bad file, since a log viewer that refuses to start over a typo is worse than one with defaults, and decide whether the stderr line is enough or the app should show a notification once it is up.
The keys are the ones the app already has state for. A new preference is one dataclass field and one place that reads it.
Run it on every Textual app gaining a preference
An automation on the Project with a linear trigger on linear.issue.labeled and the label preference starts one run per setting a user asks to keep between runs. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to read the setting from the issue, add it to Config, wire it where the app already holds that state, and extend the template and the tests.
A team maintaining several Textual tools sends this body once per repository from its own server, each POST /o/{org}/sessions naming that repository in resources with a request_id that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own CLI and reactives and chooses the keys that app can honour.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A config file is cheap to add and easy to get subtly wrong: a flag that no longer overrides the file, a reactive set after the widget mounted, a parse error that takes the app down. The agent makes the change against the real app in its own sandbox, drives it with Textual's pilot, runs the new tests on the project's Python range, and keeps the output with the pull request.
A reviewer reads a dataclass, a loader and two tests. A team with several terminal tools starts the same request across all of them, and each pull request names the keys that tool can honour.
Frequently asked questions
Where does the file live?
In the per-user config directory platformdirs resolves for the app name, ~/.config/toolong/config.toml on Linux and the platform's equivalent elsewhere, or wherever TOOLONG_CONFIG or --config points. --init-config writes a commented template there.
Which wins, the flag or the file?
The flag. The CLI options default to None so the loader can tell an absent flag from an explicit one, then the file applies, then the built-in default. The test suite checks that order for merge.
What happens with a broken file?
The app prints one line naming the file and the error, ignores it and starts with defaults; an unknown key gets the same treatment. A terminal tool should never refuse to open a log over its own settings.
Does it add a dependency for TOML?
Only below Python 3.11, where tomli is pulled in with a version marker; 3.11 and later use the standard library's tomllib. platformdirs is the other addition, for the config directory.
Why not a Textual feature for this?
Textual gives the app its reactives and bindings but no settings file, and the keys here are the app's own flags and view state, so the mapping is specific to the app. The loader is a few dozen lines and has no framework dependency.
More Textual jobs
The same job on other stacks
- Add a Config File to a Tokio Server (Tokio)
- Add a Config File to a Click CLI (Click)
- Add a Config File to a Go CLI (Go CLI)