What the agent does
The agent clones the repository into its own cloud sandbox and reads how Nix is used today. In a CLI like ajeetdsouza/zoxide, shell.nix imports nixpkgs with builtins.fetchTarball at a fixed commit and layers oxalica/rust-overlay from a second pinned tarball, then builds a mkShell with the stable Rust toolchain, a nightly rustfmt, a cargo-udeps wrapper that points at the nightly compiler, cargo-msrv, cargo-nextest, just, mandoc, nixfmt, shellcheck, shfmt, yamlfmt, markdownlint-cli, Python's black, mypy and pylint, and ten shells from bash and dash to nushell, xonsh and powershell, because tests/completions.rs and part of src/shell.rs run the generated completions under each one behind the nix-dev Cargo feature. It sets CARGO_TARGET_DIR to target_nix. The .envrc says use nix, every entry in the justfile wraps its command in nix-shell --cores 0 --pure --run, and .github/workflows/ci.yml installs Nix with cachix/install-nix-action, points nix_path at the nixos-unstable channel, which the pinned tarballs ignore, and runs just lint test. The agent also reads Cargo.toml, edition 2024 with rust-version 1.88.0, Cargo.lock, build.rs, which generates completions at build time, and the man/man1 and contrib/completions directories the Debian metadata installs.
It writes flake.nix with two inputs, nixpkgs and rust-overlay, and a flake.lock that pins them to the same two commits the tarball URLs named, so the first nix develop produces the environment the team already has rather than a newer one. devShells.default carries the mkShell over tool for tool, including the cargo-udeps wrapper and the CARGO_TARGET_DIR setting, with the toolchain still coming from the overlay so the nightly rustfmt keeps working. packages.default is new: a rustPlatform.buildRustPackage that reads the version from Cargo.toml, uses cargoLock.lockFile = ./Cargo.lock, and in postInstall copies man/man1/*.1 into share/man/man1 and the Bash, Fish and Zsh completions from contrib/completions into their standard directories, the same files the [package.metadata.deb] block ships, so nix run and nix profile install give a complete install. checks.default runs the test suite through the package build.
Then it keeps the old entry points working. shell.nix becomes a short shim that loads the flake through flake-compat, so nix-shell and the justfile commands behave as before, and .envrc changes from use nix to use flake. In ci.yml the nix_path line is dropped, since the lockfile now owns the pin, and cachix-action stays as it is because the flake's outputs push to the same cache. The agent adds flake.nix to the nixfmt lines in the justfile so just lint formats and checks it with the other Nix files, and lists flake.lock in the pull request as a file to update with nix flake update on a schedule, since the two tarball commits had no such mechanism.
To check it, the agent installs Nix in the sandbox with the single-user installer and experimental-features = nix-command flakes, runs nix flake show and nix flake metadata to confirm the inputs resolve to the pinned revisions, nix develop --command cargo nextest run --all-features --workspace to run the suite including the nix-dev shell tests inside the new dev shell, and nix build to produce the package and verify that result/bin/zoxide --version, the man pages and the completions are all present. Downloading ten shells and two Rust toolchains takes a while and is the honest cost of proving the shell is complete, and each command and its output stays in the run's record.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a Nix flake to this Rust CLI. Read shell.nix, .envrc, the justfile, every GitHub Actions workflow, Cargo.toml, Cargo.lock, build.rs and any man page or completion directories first. Write flake.nix with nixpkgs and any overlay the shell already uses as inputs, pinned in flake.lock to the same revisions the current shell.nix fetches. Carry the dev shell over tool for tool, including environment variables, as devShells.default. Add packages.default with rustPlatform.buildRustPackage using the committed Cargo.lock, installing the man pages and shell completions the repository ships, and a check that runs the tests. Replace shell.nix with a flake-compat shim so nix-shell keeps working, switch .envrc to use flake, remove any channel pin the CI workflow no longer needs, and add the new Nix files to any formatting or lint command that covers Nix files. Install Nix in your sandbox, run nix flake show, nix flake metadata, the test suite inside nix develop, and nix build, and confirm the built binary, man pages and completions exist. Open a pull request with those outputs and a note on how to update flake.lock.",
"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 adds flake.nix and flake.lock, rewrites shell.nix as a few-line flake-compat shim, changes one word in .envrc, removes the nix_path line from the CI workflow and extends two justfile lines. No Rust source changes. The description explains each output in the flake, which revision each input is locked to and that they match the old tarball URLs, and what postInstall places where.
The run's record holds the Nix install, nix flake metadata showing the locked inputs, the full cargo nextest run inside nix develop with the shell-backed completion tests included, and the nix build with a listing of result/bin, result/share/man/man1 and the completion directories, so a reviewer can see the package is complete without building it themselves.
Before merging, a reviewer decides whether to keep the flake-compat shim or delete shell.nix once everyone has moved to nix develop, whether the Cachix push should include the new package output, and how often nix flake update should run, which is a one-line schedule in a workflow or an automation.
Run it on every Rust repository with a shell.nix and no flake
In the console, an automation in the Project that has the repository, with a schedule trigger set to cron for one early morning a week, starts a run with this prompt. The prompt asks the run to finish at once if flake.nix already exists, and otherwise to do the migration, so each repository is converted once and later fires cost one file check. After the migration a second automation with the same trigger can run nix flake update, build the package and open a pull request when the lock moved, which replaces the manual bump of a tarball commit.
From your own server, send this body as POST /o/{org}/sessions with each repository in resources, with a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. Set a webhook_url on the key to receive run.completed with data.session_url when each pull request is open.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The hard part of a flake is not writing it, it is proving that nix develop gives the same tools the old shell did and that nix build produces a complete package, and that proof means downloading two toolchains and a shelf of shells into a clean store. The agent's sandbox is exactly that clean machine: it installs Nix, resolves the lock, runs the whole test suite inside the new shell and builds the package, and every command and its output is in the run's record beside the pull request, so a reviewer reads a listing instead of repeating a long build.
The same request runs across every Rust CLI an organisation maintains, each in its own sandbox with its own shell.nix and its own pinned revisions, which is how a team moves all of them to flakes with locked inputs in one review cycle rather than one evening per repository.
Frequently asked questions
Will nix-shell and direnv still work after the change?
Yes. shell.nix becomes a flake-compat shim that loads the flake's dev shell, so nix-shell and the justfile commands that call it behave as before, and .envrc moves to use flake, which direnv supports with the nix-direnv extension most Nix users already have.
Why pin flake.lock to the old revisions instead of the newest nixpkgs?
So the first nix develop reproduces the environment the team is on today and the pull request changes the mechanism, not the tool versions. Updating is then a separate nix flake update with its own diff, and the pull request says how to schedule it.
Does the package output replace the crates.io or Debian release?
No. It adds a third install path for Nix users, nix run or nix profile install from the repository, and installs the same man pages and completions the Debian package metadata lists. The release workflows are untouched.
What about the tests that need ten shells installed?
They stay behind the nix-dev Cargo feature and run inside nix develop, where the dev shell provides every shell the old shell.nix listed. The agent runs them in the sandbox, so the pull request shows the completion tests passing under the new shell.
Will the Cachix cache still be used in CI?
Yes. cachix-action watches the Nix store regardless of whether a flake or a shell.nix filled it. The only CI change is dropping the nix_path channel pin, which the lockfile makes redundant.
More Rust CLI jobs
The same job on other stacks
- Add a Nix Flake to a Go CLI (Go CLI)
More jobs like this: Hand off a long task
- Run Your Docker Images as a Non-Root User (Docker)
- Run Docker Compose Services as a Non-Root User (Docker Compose)