What the agent does
The agent reads how settings reach the program today. In a Rust CLI like ajeetdsouza/zoxide, src/config.rs is six functions over environment variables: data_dir reads _ZO_DATA_DIR or falls back to dirs::data_local_dir()/zoxide and insists on an absolute path, echo and resolve_symlinks are true when _ZO_ECHO or _ZO_RESOLVE_SYMLINKS equal 1, exclude_dirs splits _ZO_EXCLUDE_DIRS with env::split_paths into glob Patterns and defaults to the escaped home directory, fzf_opts passes _ZO_FZF_OPTS through, and maxage parses _ZO_MAXAGE as a u32 with a default of 10_000.0. src/db/mod.rs calls config::data_dir() in Database::open, and the command structs in src/cmd/ call the rest. src/cmd/cmd.rs has a HelpTemplate that prints an Environment variables section listing those six names, README.md documents them under Configuration, and man/man1/zoxide.1 has the same list. Cargo.toml is at edition 2024 with rust-version = "1.88.0", clap 4 with derive, dirs 6, serde with derive, and build.rs regenerates shell completions into contrib/completions from the clap definition.
The design keeps every existing variable working. The agent adds a Config struct in src/config.rs with serde::Deserialize and one optional field per setting, reads it once through a std::sync::OnceLock from dirs::config_dir()/zoxide/config.toml, or from the path in a new _ZO_CONFIG_FILE variable, and treats a missing file as empty. Each existing function then resolves in order: the environment variable, the file's field, the default. exclude_dirs takes a TOML array of strings rather than a path-separated list, maxage an integer, echo and resolve_symlinks booleans, and data_dir and fzf_opts strings, so a file value is validated with the same Pattern::new, parse::<u32> and is_absolute checks and an error names the file and the key. The toml crate is added with the smallest feature set that parses, which matters because just lint runs cargo udeps and cargo msrv verify, so the chosen version must build on 1.88.0 and every feature must be used.
Documentation changes in three places so they do not drift. The HelpTemplate in src/cmd/cmd.rs gains a Configuration file line under the environment variables, with the path and a note that variables win; man/man1/zoxide.1 gets a FILES section and a line per key, written so mandoc -man -Wall -Tlint passes; and README.md's Configuration section gets a config.toml example with every key and its default, formatted so markdownlint passes. templates/ and init.fish are untouched, since the shell init scripts never read these settings directly.
Tests sit beside the code. Unit tests in src/config.rs use tempfile for a directory, write a config.toml, point _ZO_CONFIG_FILE at it and check the three-way precedence for each key, plus the error text for a relative data_dir and a bad glob. An integration test in tests/ uses assert_cmd like tests/completions.rs does, runs zoxide add and zoxide query with a config file that sets data_dir to a temporary directory, and checks the database lands there. The agent runs what justfile runs: cargo fmt --all --check, cargo clippy --all-features --all-targets -- -Dwarnings, cargo msrv verify, cargo udeps, the mandoc, markdownlint, shellcheck, shfmt and yamlfmt lints, and cargo nextest run --all-features --no-fail-fast --workspace, inside the nix-shell the justfile names or with the tools installed directly.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labelled agent says: \"Add a config file. Every _ZO_ setting should be settable in a TOML file in the user's config directory, with environment variables still taking precedence.\" Do the work in this repository. Read Cargo.toml, build.rs, src/main.rs, src/config.rs, src/cmd/cmd.rs, src/db/mod.rs, tests/completions.rs, justfile, .github/workflows/ci.yml, README.md and man/man1/zoxide.1 first. Add a serde Config struct read once from dirs::config_dir()/zoxide/config.toml or the path in _ZO_CONFIG_FILE, with a missing file treated as empty. Resolve each setting as environment variable, then file, then default, and validate file values with the same checks the variables get, naming the file and key in errors. Add the toml crate with minimal features that build on the pinned rust-version. Document the file in the help template, the man page and the README. Add unit tests for the precedence and the errors and an assert_cmd test that runs the binary with a config file. Run the full just lint and just test targets, and open a pull request that shows a complete example file.",
"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
What comes back is a pull request that changes Cargo.toml and Cargo.lock, src/config.rs, the help template in src/cmd/cmd.rs, man/man1/zoxide.1 and README.md, and adds an integration test under tests/. The description shows a full config.toml with every key and its default, states the precedence rule in one line, and quotes the clippy, msrv, udeps, mandoc, markdownlint and nextest summaries.
The transcript holds every lint from the justfile, the cargo msrv verify result that proves the new crate builds on 1.88.0, the cargo udeps run that proves nothing unused was added, and the nextest run with the new cases, so a reviewer sees the same checks CI will repeat rather than a claim that they pass. GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff file by file.
Before merging, a reviewer checks that a file with an unknown key is rejected rather than ignored, that _ZO_CONFIG_FILE pointing at an unreadable path is an error while a missing default file is not, that the help text still fits the template's column layout, and that the man page passes mandoc with no warnings. A follow-up message to the same session adds a zoxide config subcommand that prints the resolved settings, and the sandbox still has the toolchain and the lint tools.
Run it on every Linear issue labelled agent
In the Project that holds the CLI, add an automation with this prompt and a linear trigger on linear.issue.labeled filtered to the agent label. Each labelled CLI issue starts its own run in its own sandbox and ends in its own pull request; the issue text follows the prompt as data, and the trigger fills in no placeholder.
A handler on your own server does the same without the automation: it receives Linear's webhook, puts the issue text into input, and sends POST /o/{org}/sessions with the repository in resources and a request_id that is a UUID v5 of the issue id, so a redelivered webhook returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The lint target here is nine tools under Nix, and a new dependency has to pass cargo msrv verify and cargo udeps as well as clippy with warnings denied. On a laptop that is an afternoon of tool installs before the first run. In a Rush sandbox the agent sets up that toolchain itself, runs the whole lint and test set as many times as the change needs, and keeps every run in the record.
A config file touches the help, the man page and the README at once, and the pull request has to show all three agree. The transcript holds the mandoc and markdownlint runs beside the tests, so a reviewer checks the documentation the same way as the code. Several CLIs can gain a config file at once, each in its own sandbox, each with its own pull request.
Frequently asked questions
Will my existing _ZO_ variables stop working?
No. Each setting resolves as the environment variable first, then the file, then the default, so a variable set today behaves exactly as before and the file only fills in what the environment leaves unset.
Where does the file live?
At dirs::config_dir()/zoxide/config.toml, which is the platform's config directory, or wherever _ZO_CONFIG_FILE points. A missing default file is treated as empty; a _ZO_CONFIG_FILE that cannot be read is an error that names the path.
How are bad values reported?
With the same checks the variables use: a relative data_dir, a glob that does not parse in exclude_dirs and a non-integer maxage each produce an error that names the file and the key. An unknown key is rejected so a typo does not silently do nothing.
Does this change the shell init scripts or completions?
No. The templates/ the init command renders and the completions build.rs generates do not read settings, and the prompt leaves them alone. build.rs regenerates contrib/completions only if the clap definition changes, which this does not.
Why TOML?
It is the format Cargo already uses, the toml crate deserialises through the serde the project depends on, and the file is small enough that any format reads the same. Say YAML or JSON in the prompt if your users expect one of those.
More Rust CLI jobs
The same job on other stacks
- Add a Config File to a Textual App (Textual)
- Add a Config File to a Tokio Server (Tokio)
- Add a Config File to a Click CLI (Click)