Toad
A testing agent for the web apps and command-line programs you build. You say what should work, in plain words. Toad tests it and comes back with a verdict and the receipts to prove it.
Toad is built to be called by your coding agent: Claude Code, Pi, Codex, Cursor or any MCP client. The agent hands Toad a test, Toad runs it independently, and the agent gets back evidence instead of its own opinion of its work.
npm install -g github:mihaiiova/toad && toad setup
What you get back#
Every run ends with:
- A verdict:
PASS,FAILorERROR. A scenario that could not be run (the site was down, a secret was missing) isERROR, never a quietFAIL. - A report per scenario: what was done, what was expected, what happened.
- Receipts: a screenshot for every web step, and a record of every command (exit code, output, duration) for CLI steps.
Everything is saved in your project under .toad/runs/, and you can browse
it in the run viewer.
What it tests#
| How | |
|---|---|
| Web apps | A real headless Chromium on your machine, so localhost works. It clicks, types and submits forms. |
| CLIs | A copy of your project in a locked-down Linux container (Docker or Podman), or Bubblewrap on Linux. It never changes your files. |
How a run works#
- You ask your coding agent, in plain words, to test something.
- The agent writes a handoff: the target, the goal, and scenarios with expected outcomes. Secrets go in by name only, never by value.
- Toad’s lead agent splits the handoff into scenarios and gives each to a specialist: a web-tester that drives the browser, or a cli-tester that runs commands in the sandbox.
- The testers report only what they observed. The lead writes the report, and your agent gets the verdict, the report and the receipt paths.
More detail is in How it’s built.
Built with Pi Forge#
Toad’s testing agent was designed and generated with Pi Forge, the workshop the Mighty Agents come from, and it pins a Forge release like any other generated agent. In return, Toad is what tests Pi Forge. Each keeps the other honest.
Next#
- Install Toad, about five minutes.
- Connect your coding agent.
- Test your first project.