funzzy for Mac

Funzzy (fzz)

Run the right checks after each edit, and see the result of that run.

Funzzy watches files and runs matching jobs from one YAML configuration. Developers and coding agents can read each run's status and output. They do not need to guess which result belongs to their last edit.

Why Funzzy? One workflow: use the same YAML file for watch mode, local runs, editors, CI, and agents. Predictable execution: Funzzy runs jobs in declared order. Named groups enable parallel work. Cancellation stops the complete process tree. Long-running services: a readiness check confirms that a service started correctly. The service can then stay active. Exact feedback: local tools can use a control socket. They can read status and output or cancel a specific run. Changed paths as data: scripts can read the complete file-change batch as JSON instead of interpolating filenames into shell commands. Agent access: agents can discover the config schema and inspect exact run results through the CLI.

Funzzy has two equivalent binary names: funzzy and the shorter fzz. This README uses fzz.

A quick glimpse

Create .watch.yaml:

Then use one of four paths:

A secondary worktree can run checks without starting services:

Declaration order is important. Consecutive jobs with the same parallel name can run at the same time. Other jobs run in sequence.

The changed-files job runs Node 18+ inline; no script file is needed. It reads FZZ_TRIGGER_PATHS_FILE as a JSON array for the complete filesystem-change batch and prints each literal path as a JSON string, including spaces and newlines. Init and manual runs receive no batch pointer, so the job exits without output. Read the file while Funzzy supervises the job or service; hooks do not receive the pointer implicitly. Node and Python walkthroughs show longer scripts for real work.

Changed paths in job scripts

For new job scripts, read changed paths from child environment data: FZZ_TRIGGER_PATH: one trigger path. FZZ_TRIGGER_RELATIVE_PATH: that path relative to the job's cwd. FZZ_TRIGGER_PATHS_FILE: private JSON file containing the complete changed-path batch as literal paths.

These values exist only for filesystem-triggered job children. Init and manual runs are pathless and receive none of them. Hooks do not receive them. Read the batch file while Funzzy supervises the job or service.

Start in one minute

Install Funzzy with one of these commands:

See Installation for Nix, pinned releases, source builds, and platform details.

Create and inspect a workflow:

fzz init does not overwrite an existing configuration. Use fzz migrate to convert an accepted old configuration to the jobs: form.

If you use Pi, you can ask it to add your project's checks after initialization: [!NOTE] V2 (2.0.1) is the current line. Version 1.5.0 remains on the v1 branch. See the migration guide.