# Persist User Settings in a Textual App

Yes. An agent saves a Textual app's toggles to a JSON file in the user's config directory, restores them on the next launch and proves it with Textual's pilot tests.

[Run this on Rush](https://cloud.getrush.ai/run/add-persistent-settings/textual/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads what the app lets a person change before deciding what to save. In an app laid out like Textualize/toolong, `src/toolong/cli.py` is a click command that takes files, `-m/--merge` and `-o/--output-merge` and builds `UI(files, merge=merge, save_merge=output_merge)`. `src/toolong/ui.py` defines `UI(App)`, whose `on_mount` sets `ansi_theme_dark` and pushes a `LogScreen` with one `TabPane` per file. `src/toolong/log_view.py` holds the state a person toggles: `LogView` has reactives `show_find`, `show_panel`, `show_line_numbers`, `tail` and `can_tail`, bound to `ctrl+t` for `toggle_tail` and `ctrl+l` for `toggle('show_line_numbers')`, and `data_bind`s them into `LogLines`. `src/toolong/find_dialog.py` has a `Case sensitive` and a `Regex` checkbox whose `Update` message `LogView` copies into `LogLines.regex` and `LogLines.case_sensitive`. None of this survives quitting: every launch starts with line numbers off, tail off and a plain-text, case-insensitive search.

The settings become one dataclass in `src/toolong/settings.py`: `show_line_numbers`, `tail`, `regex` and `case_sensitive`, all `False` by default, with `load()` and `save()` that read and write `settings.json` under the user's config directory from `platformdirs`, added to `pyproject.toml` beside `click` and `textual`. A missing or unreadable file yields the defaults and a warning in the app's log, never a crash, and `TOOLONG_SETTINGS` set to a path overrides the location for tests and for people who keep dotfiles elsewhere. `UI.__init__` loads them once and keeps them on the app; `LogView.compose` seeds its reactives from them, and the two checkboxes in `FindDialog` start with the saved values.

Saving happens where the value changes. `LogView` gains `watch_show_line_numbers` and extends `watch_tail` to write the new value, and `filter_dialog_update` writes `regex` and `case_sensitive` when a `FindDialog.Update` arrives. The write is a small JSON file through a temporary name and `os.replace`, so a crash mid-write cannot leave a half file. `tail` is saved only when `can_tail` is true, since a merged view cannot tail and the stored preference should keep meaning the last choice a person made in a tailable view. Nothing per file is stored, so opening a new log looks like the last one a person tuned.

The repository has no tests and no workflow, so the proof is new: `pytest` and `pytest-asyncio` in the poetry dev group and `tests/test_settings.py`. One test writes a temporary log, points `TOOLONG_SETTINGS` at a path under `tmp_path`, runs `UI([path]).run_test()`, presses `ctrl+l` through the pilot, exits, and asserts the file holds `show_line_numbers: true`; a second starts a fresh `UI` against that file and asserts `LogLines.show_line_numbers` is already true after mount; a third writes a corrupt file and asserts the app still starts with defaults; a fourth toggles the regex checkbox in the find dialog and checks the saved value. `poetry run pytest` and `poetry run tl --help` end the run.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Persist user settings in this Textual app. Read src/toolong/cli.py, src/toolong/ui.py, src/toolong/log_view.py, src/toolong/log_lines.py, src/toolong/find_dialog.py and pyproject.toml first. Add src/toolong/settings.py with a dataclass holding show_line_numbers, tail, regex and case_sensitive, and load and save functions that use settings.json in the user config directory from platformdirs, overridable with a TOOLONG_SETTINGS path. A missing or corrupt file gives the defaults and a logged warning. Load once in UI.__init__, seed LogView's reactives and the find dialog's checkboxes from the saved values, and save when show_line_numbers, tail (only while can_tail), regex or case_sensitive change, writing through a temporary file and os.replace. Add pytest and pytest-asyncio to the dev group and write tests/test_settings.py using App.run_test and the pilot: toggling line numbers writes the file, a fresh app reads it back, a corrupt file falls back to defaults, and the regex checkbox is saved. Run poetry install, poetry run pytest and poetry run tl --help, document the file in README.md, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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/settings.py` and `tests/test_settings.py`, changes `src/toolong/ui.py`, `src/toolong/log_view.py`, `src/toolong/find_dialog.py`, `pyproject.toml`, `poetry.lock` and `README.md`, and leaves `cli.py` alone, because the command line flags are per invocation and stay that way. Its description pastes the pytest run with the four tests named and the JSON file one of them produced, so a reviewer sees the exact keys a person's config directory will hold.

The next launch after someone turns line numbers on opens with them on, in every tab, and the find dialog remembers regex and case sensitivity. A person who never touches a toggle sees no file written, since the first save happens on the first change, and a broken file costs a warning in the log rather than a traceback at start.

Before merging, a reviewer decides whether `tail` belongs in the file at all, since a saved tail on a large file starts scrolling at once, and whether the README should name the path per platform, which `platformdirs` resolves differently on Linux, macOS and Windows.

## Run it on every Linear issue labelled agent

Label the issue that names the toggles a person keeps resetting, and an automation in the Project with a `linear` trigger on `linear.issue.labeled` and the label `agent` starts one run per labelled issue, with the issue's text after the automation's prompt. The prompt asks for the same shape every time: one settings module, values seeded where the widgets are composed, saves in the watchers, and pilot tests that quit and relaunch the app. A run whose issue names a value the app already persists opens no pull request and says so on the issue.

Each run opens its own pull request that links the issue, so the person who labelled it reviews the diff and the test output there. The automation's `max_runs_per_hour` caps a burst of labels, and a label added twice is deduplicated on Linear's delivery id.

## Why run it on Rush?

Persisting state in a terminal app touches the reactive system in the right order or not at all: a value seeded after `compose` flashes the default first, a save in the wrong watcher fires during mount and writes defaults over a saved file. The agent reads where each reactive is declared and bound before adding the watchers, and proves the round trip by quitting and relaunching the app under Textual's pilot in its sandbox.

The run keeps every command and its output, so the reviewer reads the pytest run and the resulting JSON without installing poetry or a terminal that can run the app. Several Textual apps can be given a settings file at once, each in its own sandbox, and one that already has a config module gets only the new keys and the tests.

## Frequently asked questions

### Why platformdirs instead of a hard-coded ~/.config path?

Because the app supports Python 3.8 and up on any platform, and the config directory differs on macOS and Windows. `platformdirs` is one small pure-Python dependency, and the `TOOLONG_SETTINGS` override keeps tests and dotfile managers away from the real directory.

### Does the merge flag get saved?

No. `-m` and `-o` are arguments to one invocation in `cli.py`, and saving them would make `tl file.log` silently merge the next time. Only toggles a person flips inside the running app are stored.

### What if two tabs disagree?

Each `LogView` saves when its own value changes, so the file holds whatever was toggled last. On the next launch every tab starts from that value, which matches how `ctrl+l` already applies to the tab in front of you.

### How do the tests drive the app without a terminal?

`App.run_test` runs the app headless and returns a pilot that presses keys and waits for the screen to settle, so a test can press `ctrl+l`, exit, and read the file. The tests use a temporary log and a temporary settings path, so they never touch a developer's real config.

## More Textual jobs

- [Add Pre-commit Hooks to a Textual App](https://getrush.ai/run/add-pre-commit-hooks/textual/)
- [Add a Release Workflow for a Textual App](https://getrush.ai/run/add-release-workflow/textual/)
- [Add Shell Completion to a Textual App's CLI](https://getrush.ai/run/add-shell-completion/textual/)

## The same job on other stacks

- [Add Persistent User Settings to an Electron App from a Linear Issue](https://getrush.ai/run/add-persistent-settings/electron/)
- [Persist User Settings in a Tauri App](https://getrush.ai/run/add-persistent-settings/tauri/)

## More jobs like this: Turn a Linear label into a PR

- [Add PHPStan Static Analysis to a PHP Library](https://getrush.ai/run/add-phpstan/php/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
