canary

Canary

Canary is an AI-powered test automation agent that transforms natural language requirements into high-quality, framework-aware test code.

🚀 Features

• Intent Classification: Automatically detects if you need E2E, API, Unit, or Performance tests.
• Framework Recommendation: Suggests the best-in-class tool (Playwright, Vitest, Pytest, k6) based on your needs.
• Code Generation: Produces production-ready test scripts following industry best practices.
• CLI-First: Simple terminal interface for seamless developer workflow.

🛠 Installation

pipx (recommended)

pipx install git+https://github.com/bop-clocktower/canary@latest

This installs the canary binary globally without polluting your project virtualenv. Upgrade by re-running with @<new-tag>.

From source

git clone https://github.com/bop-clocktower/canary.git
cd canary
pip install -e .

Claude Code plugin

Canary ships as a Claude Code plugin with four MVP personas — canary-test-author, canary-test-reviewer, canary-framework-advisor, and canary-flake-hunter — plus the harness MCP server. Add it as a local marketplace:

/plugin marketplace add https://github.com/bop-clocktower/canary
/plugin install canary@bop-clocktower

Or, if you've already cloned the repo:

/plugin marketplace add /path/to/canary
/plugin install canary@bop-clocktower

Note: the install syntax is <plugin-name>@<marketplace-name>. The canary plugin ships from the bop-clocktower marketplace, so the @ qualifier reads as canary@bop-clocktower.

No separate API key is required. The plugin runs through Claude Code's own session authentication.

📖 Usage

Generate Tests (Claude Code plugin)

Test generation runs inside Claude Code — no API key, no LLM provider setup. Invoke a persona from your editor session:

/canary-write-test  Create a Playwright test for the login flow on https://example.com

The canary-test-author agent classifies the intent, picks a framework, reads your repo for context via the Canary MCP tools, and writes the test using your Claude Code session.

Recommend a Framework (CLI)

The CLI is deterministic and needs no key. To see Canary's framework recommendation and reasoning for a requirement:

canary recommend "I need a load test for my checkout API"

Other deterministic CLI commands: canary init <framework> (scaffold a suite), canary run <file> <framework> (execute a test), canary migrate (adopt a harness-scaffolded project), canary version.

⚙️ Configuration

No API key is required. Canary runs as a Claude Code plugin and uses your Claude Code session for any LLM work — there is no separate provider key to set. The CLI commands (recommend, init, run, migrate) are deterministic and make no LLM calls.

📝 Changelog

See CHANGELOG.md for release history. Per-release notes are also published on GitHub Releases.

🏗 Architecture

Canary follows a modular pipeline: User Prompt → Classifier → Recommender → host LLM (your Claude Code session) → Generated Test

Generated by Canary — The future of autonomous test engineering.