# Add Fuzz Tests to a Rust CLI's Parser

Yes. An agent adds a cargo-fuzz crate that feeds random input to your Rust CLI's lexer and parser, fixes any panic it finds, and opens a PR with the targets.

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

## What the agent does

The agent reads how the tool turns text into a program. In a CLI shaped like casey/just, the pipeline is `Lexer::lex` in src/lexer.rs, a hand-written character-by-character lexer, then `Parser::parse_tokens` in src/parser.rs, a recursive descent parser with a `recursion_depth` field, then `Analyzer::analyze` in src/analyzer.rs; `Compiler::test_compile` in src/compiler.rs already strings the three together for unit tests, but it is `#[cfg(test)]` and every stage is `pub(crate)`. The only public entry is `just::run` in src/run.rs, which parses command-line arguments and reads a justfile from disk. The .gitignore already lists `/fuzz/artifacts`, `/fuzz/corpus` and `/fuzz/target`, so someone fuzzed this parser once on a laptop and never checked the harness in.

It then gives the fuzzer a door without widening the API. A `fuzzing` feature in Cargo.toml gates a small `pub mod fuzz` with one function that takes a `&str`, lexes it, parses the tokens and runs the analyzer the way `test_compile` does, discarding the result; nothing is exported when the feature is off, so `unreachable_pub = "deny"` in the `[lints.rust]` table and the public surface documented on docs.rs are untouched. The fuzz crate goes in fuzz/ with its own `[workspace]` table, because the root Cargo.toml lists `members = [".", "crates/*"]` and a nested crate would otherwise be claimed by the outer workspace.

Two targets go in fuzz/fuzz_targets: `compile`, which hands arbitrary bytes that happen to be UTF-8 to the gated function, and `roundtrip`, which parses, prints with the `--dump` formatting path and parses again, asserting the second parse succeeds. The second one is where a formatter bug shows up as a crash rather than a quiet diff. A seed corpus is built from the repository's own justfile and the files in examples/, so the first minutes are spent on realistic input rather than on random bytes. cargo-fuzz needs a nightly toolchain, which the justfile's `install-dev-deps` entry already installs, so the agent uses `cargo +nightly fuzz run compile -- -max_total_time=300` for each target.

Any crash becomes a regular test. A panicking input is minimised with `cargo fuzz tmin`, copied into the integration suite under tests/ as a case that expects a clean error rather than a panic, and the fix is made in the lexer or parser with that test failing first. The agent runs `cargo test --all`, `cargo clippy --all --all-targets` under the repository's `RUSTFLAGS: --deny warnings` and the pedantic lint set in Cargo.toml, `cargo fmt --all -- --check` with the two-space rustfmt.toml, and `bin/forbid`, which rejects any dbg macro call or todo left in the tree; all four are what ci.yaml runs.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add cargo-fuzz targets for this Rust CLI's lexer and parser. Read Cargo.toml, src/lib.rs, src/lexer.rs, src/parser.rs, src/analyzer.rs, src/compiler.rs, src/run.rs, src/testing.rs, tests/lib.rs, justfile, rustfmt.toml, clippy.toml, bin/forbid, .gitignore and .github/workflows/ci.yaml first. Add a fuzzing cargo feature that exposes one public function taking a &str and running lex, parse and analyze the way Compiler::test_compile does; export nothing when the feature is off, and keep unreachable_pub satisfied. Create fuzz/ with its own workspace table so the root workspace members list is unchanged, with two targets: compile, and a roundtrip that parses, prints with the dump formatting and parses again. Seed the corpus from the justfile and examples/. Run each target with cargo +nightly fuzz run for a bounded time. Minimise any crash with cargo fuzz tmin, add it as an integration test expecting a clean error, and fix the cause with that test failing first. Run cargo test --all, cargo clippy --all --all-targets with RUSTFLAGS set to deny warnings, cargo fmt --all -- --check and bin/forbid. Add a fuzz entry to the justfile and a short Fuzzing section to CONTRIBUTING.md, then open a pull request that quotes the fuzz run summaries and the test 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

What comes back is a pull request on its own branch with fuzz/Cargo.toml, fuzz/fuzz_targets/compile.rs and fuzz/fuzz_targets/roundtrip.rs, a seed corpus under fuzz/corpus that .gitignore does not cover once the agent narrows the ignore to artifacts and target, a `fuzzing` feature and a gated module in src/lib.rs, a `fuzz` entry in the justfile, and a Fuzzing paragraph in CONTRIBUTING.md. If a crash was found, the diff also carries a minimised test case in tests/ and the one-line or ten-line fix in src/ that makes it pass.

The description quotes each target's run summary as libFuzzer printed it, the executions and corpus size at the time limit, and either `no crashes` or the minimised input with its panic message and the commit that fixes it. It quotes `cargo test --all`, the clippy result under the pedantic configuration and the `bin/forbid` result, because those are the four checks ci.yaml enforces and the reviewer should not have to re-run them to trust the branch.

Before merging, a reviewer reads the gated module to confirm the public API is unchanged when the feature is off, decides whether the corpus belongs in the repository or in a separate artifact, and whether to add a scheduled workflow that runs the targets for a few minutes a night. A follow-up on the same session can write that workflow with the targets already proven to build.

## Run it on every parser change

The first run adds the harness; the later runs use it. An automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt `Run the fuzz targets under fuzz/ for ten minutes each against this branch and report any new crash as a minimised test case` starts one run per push to a pull request that touches src/lexer.rs or src/parser.rs. The trigger adds the pull request after the prompt; it fills in no placeholder, and only work by an owner, member or collaborator fires it.

The same prompt on a schedule, once a night, keeps the corpus growing on `master` without anyone's laptop, and each run's record shows the exact executions and the corpus it started from. A run that finds a crash ends with a pull request carrying the failing test and a fix, or with `needs_review` and the minimised input when the fix is not obvious.

## Why run it on Rush?

Fuzzing is the test nobody runs on a laptop because it occupies a core for an hour and needs a nightly toolchain. In its own sandbox the run installs nightly, builds the instrumented targets, lets them run for the bounded time the prompt sets, and keeps every libFuzzer line in the transcript. There is nothing to clean up afterwards and the laptop was never involved.

The record is what makes a fuzz finding reviewable. The transcript shows the crash input, the `tmin` minimisation, the test written before the fix and the test passing after it, in that order. A reviewer who wants a different fix can say so in a follow-up and the parked sandbox still has the corpus, the nightly toolchain and the instrumented build.

## Frequently asked questions

### Does this change the crate's public API?

Only behind the fuzzing feature, which is off by default and off on docs.rs. With the feature off nothing new is exported, unreachable_pub stays satisfied, and a downstream crate sees the same just::run it sees today.

### Why a separate workspace for the fuzz crate?

Because the root Cargo.toml lists members as the root and crates/*, and a crate under fuzz/ would be pulled into that workspace, where its libfuzzer-sys dependency and nightly-only flags would affect every cargo command. cargo fuzz init writes its own workspace table for exactly this reason.

### Will the fuzzers run in CI?

Not in the pull request's own CI, which keeps the ci.yaml matrix as it is. The pull request adds a justfile entry to run them locally and describes a nightly scheduled run on Rush; a reviewer can ask for a GitHub Actions job in a follow-up if they prefer.

### What if it finds a crash it cannot fix?

The minimised input and the panic go into the pull request as a test marked to be fixed, with the fuzz summary showing how it was found, and the run ends needs_review rather than claiming a clean result. The reviewer then decides whether to fix it on the same session or on a branch of their own.

### Does it need the nightly toolchain forever?

Only to run the fuzzers. cargo-fuzz uses sanitizer and coverage flags that stable does not expose, so the justfile's fuzz entry uses cargo +nightly; the gated module, the tests and the fix all build on the stable toolchain the ci.yaml msrv job checks.

## More Rust CLI jobs

- [Add JSON Output to a Rust CLI](https://getrush.ai/run/add-json-output/rust-cli/)
- [Generate a Man Page for a Rust CLI With clap_mangen](https://getrush.ai/run/add-man-page/rust-cli/)
- [Add a Minimum Supported Rust Version Check to a Rust CLI](https://getrush.ai/run/add-msrv-check/rust-cli/)

## The same job on other stacks

- [Add Fuzz Tests to a Tokio Protocol Parser](https://getrush.ai/run/add-fuzz-tests/tokio/)
- [Add libFuzzer Fuzz Tests to a CMake Project](https://getrush.ai/run/add-fuzz-tests/cmake/)
- [Add Fuzz Tests to a Go CLI](https://getrush.ai/run/add-fuzz-tests/go-cli/)

## 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/)
