Quickstart

Set Ferret loose in five minutes.

Install the CLI, authenticate, and run a hunt on your current branch. The first catch usually lands before your coffee does.

1. Install

Ferret runs from npm. No global daemon, no config file required to start.

terminal

# run without installing
npx ferret --version
 
# or add it to your project
npm install -D ferret

2. Authenticate

terminal

npx ferret login
# opens the browser, grabs a scoped token

3. Run a hunt

Point Ferret at the changes on your branch. It analyzes, writes a failing test for each defect it can prove, and proposes a fix.

terminal

npx ferret hunt --diff main
 
  analyzing 3 changed files ...
  1 defect caught
 
  ✗ src/lib/user-cache.ts:14  poisoned cache on rejected fetch
    failing test  → src/lib/user-cache.test.ts
    proposed fix  → run: npx ferret apply

Want the full walk-through with real code, from a clean repo to a merged fix? Read Your first hunt.

CI integration

Add the GitHub Action and Ferret hunts on every pull request. It comments each catch inline with the failing test and the fix. Set fail-on: new-defects to block a merge only when the branch introduces a defect Ferret can reproduce.

.github/workflows/ferret.yml

name: ferret
on: [pull_request]
 
jobs:
  hunt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ferret-dev/hunt@v1
        with:
          fail-on: new-defects
          token: ${{ secrets.FERRET_TOKEN }}

Configuration

Defaults are sensible. When you want to tune scope, drop a ferret.config.ts at the repo root.

ferret.config.ts

import { defineConfig } from "ferret";
 
export default defineConfig({
  // paths Ferret should hunt through
  include: ["src/**/*.{ts,tsx}"],
  exclude: ["**/*.generated.ts"],
  // your test runner, so reproductions match your setup
  testFramework: "vitest",
  // only surface defects at or above this confidence
  minConfidence: "high",
});

Languages

Ferret hunts in these today. The failing test is written in your project's existing framework.

TypeScript / JavaScript · Vitest, Jest
Python · pytest
Go · go test
Ruby · RSpec, minitest
Java · preview
Rust · preview

Your first hunt Start hunting