Glossary

The Watchfire glossary.

Name: Watchfire
Author: Watchfire

Plain-English definitions of every Watchfire term, mode, and concept — the canonical reference any other page on the site can link to. 27 terms across 5 categories. Use the filter or jump to a section.

Modes

The six ways an agent can be run against a project — from a single interactive chat to an autonomous loop that generates its own work.

Chat modealso: chat, interactive modeDocs →: An interactive session with the agent — closer to a normal coding-CLI conversation than a task run. No task file, no automatic merge: useful for exploring a codebase, prototyping, or asking the agent a one-off question inside a project's worktree.
Task modealso: task run, task executionDocs →: Runs one specific task from .watchfire/tasks/ in an isolated git worktree. The agent reads the task's prompt and acceptance criteria, makes changes, commits, and updates the task file when done. This is the unit Watchfire is built around.
Start Allalso: start-all, run all ready tasksDocs →: Sequentially runs every task currently in ready status. Each task gets its own worktree and its own sandboxed agent process; failed ones stop being retried but never block the next task from starting.
Wildfire modealso: wildfire, autonomous mode, wildfire loopDocs →: The autonomous loop. Wildfire alternates between executing ready tasks, refining drafts, and generating new draft tasks from the project definition until you stop it. The worktree and sandbox keep the blast radius bounded even when nobody is watching.
Generate definitionalso: definition generate, watchfire definition generateDocs →: Asks the agent to draft a project definition by reading the repo — tech stack, layout conventions, code style, gotchas. The output lands in .watchfire/project.yaml under definition: and you can keep editing it afterwards.
Generate tasksalso: task generate, watchfire generateDocs →: Asks the agent to propose new tasks against the project definition. Generated tasks land as draft YAML files so you can read, edit, and promote the good ones — Watchfire never silently executes a task it generated itself.

Concepts

The building blocks: projects, tasks, the worktree-and-sandbox pairing, and the agent backend Watchfire happens to be driving.

Projectalso: watchfire projectDocs →: A repo Watchfire knows about. Created by running watchfire init, which adds a .watchfire/ directory with a project.yaml, a tasks/ folder, and a worktrees/ parent. Projects are independent — one machine can manage many in parallel.
Taskalso: task file, task yamlDocs →: A unit of work described as a small YAML file at .watchfire/tasks/<n>.yaml. Contains a title, prompt, acceptance criteria, and status. Tasks are plain text by design — editable in your editor, diffable in git, runnable by any client.
Worktreealso: git worktree, task worktreeDocs →: Each task gets its own git worktree at .watchfire/worktrees/<n>/ on a dedicated watchfire/<n> branch. Parallel tasks never touch each other's files, a failed run never pollutes main, and a finished task can be reviewed like any other branch before merging.
Sandboxalso: seatbelt, sandbox-exec, landlock, bubblewrapDocs →: The kernel-level isolation each agent process runs inside: Seatbelt (sandbox-exec) on macOS, Landlock on Linux 5.13+, Bubblewrap as a fallback. It denies access to ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, ~/.npmrc, and .git/hooks by default. Enforcement is at the kernel level, not on the agent being well-behaved.
Beaconalso: watchfire beacon: The signal a task emits to mark itself complete — concretely, the moment its YAML file flips to status: done. The daemon watches .watchfire/tasks/ and reacts to that change: if auto_merge is on and success: true, the worktree's branch is merged into the default branch.
PTYalso: pseudo-terminal, pseudo terminal: Pseudo-terminal. Every agent backend is itself a CLI, so Watchfire spawns it inside a PTY — that's what lets terminal-UI agents render normally, lets the daemon capture the live transcript, and lets the TUI and GUI replay output without re-running the agent.
Agent backendalso: agent CLI, backend, agentDocs →: The coding agent CLI Watchfire is driving — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot CLI, or Cursor Agent. Watchfire doesn't bundle a model; pick a backend per project in project.yaml and Watchfire reuses that CLI's existing auth.

Components

The three pieces of software you actually run — one daemon, plus the CLI/TUI and GUI clients that talk to it.

Daemon (watchfired)also: watchfired, watchfire daemonDocs →: The single orchestrator process. Spawns agent PTYs, manages git worktrees, watches task files, tracks status, and serves gRPC to every client. Lives at ~/.watchfire/daemon.yaml; start with watchfire daemon start or watchfired --foreground for live logs.
CLI / TUI (watchfire)also: watchfire CLI, watchfire TUI, tuiDocs →: The watchfire binary — a thin gRPC client to the daemon that doubles as an interactive Bubbletea-based TUI. The CLI form is for scripts and one-off commands; the TUI is the keyboard-driven dashboard for running tasks and monitoring agents.
GUI (Watchfire.app)also: watchfire gui, watchfire desktop, watchfire appDocs →: The Electron desktop client. Multi-project view with live agent terminal output, point-and-click task management, and a system tray. Shares state with the CLI/TUI through the same daemon — open both at once and they stay in sync.

Lifecycle

Task status, outcome flags, and the auto-merge settings that decide what happens when a run finishes.

draftalso: status: draft: A task status meaning "don't run me yet." Drafts are safe to edit. Wildfire's refine phase improves drafts before promoting them, and generated tasks always land as drafts so you can review them before flipping to ready.
readyalso: status: ready: A task status meaning "safe to execute." If auto_start_tasks is on, the daemon picks ready tasks up immediately; otherwise they sit in the queue waiting for Task mode, Start All, or Wildfire to consume them.
donealso: status: done, completed task: A task status set by the agent when a run finishes — successfully or not. Read the success flag to know which. The daemon's file watcher reacts to done to trigger auto-merge or, on failure, to keep the worktree around for inspection.
successalso: success: true, success: false: Boolean outcome flag on a completed task. true means the agent finished the work; false means it bailed, was blocked, or hit something it couldn't recover from. Pair success: false with a non-empty failure_reason.
failure_reasonalso: failureReason: Free-text field on a task that explains why success is false. Show it in reviews so a human knows whether to retry, redefine, or drop the task entirely. Always empty for successful tasks.
auto_mergealso: auto merge, automerge: Per-project setting (chosen at watchfire init) that decides whether a successful task's branch is merged into the default branch automatically. With it off, the worktree lands on watchfire/<n> and waits for you to merge by hand.
auto_delete_branchalso: branch cleanup: Per-project setting that decides whether the watchfire/<n> branch and its worktree are deleted after a successful auto-merge. Convenient for hands-off runs; turn it off if you want to keep the branch history for review.

Config

The YAML files and definition text Watchfire reads from `.watchfire/` to know what to build and how.

project.yamlalso: project config, project fileDocs →: The per-project config file at .watchfire/project.yaml. Holds the project id, name, default branch, default agent backend, sandbox settings, auto-merge toggles, the next-task counter, and the project definition. Edit it in place or via watchfire settings.
task.yamlalso: task config, task.yaml schemaDocs →: An individual task file at .watchfire/tasks/<n>.yaml. At minimum it has title, prompt, acceptance_criteria, and status. The daemon fills in IDs and timestamps after a run; never write timestamps as empty strings — leave the fields off and let the daemon populate them.
next_task_numberalso: task counter: Monotonic counter in project.yaml used to name the next task file (.watchfire/tasks/0157.yaml, 0158.yaml, …). Watchfire bumps it whenever it creates a task; agents creating tasks autonomously read this counter to pick their next filename.
definitionalso: project definition: Free-form description of what the project is and how the agent should approach it — stack, conventions, gotchas. The daemon injects it into the agent's system prompt at launch. You can write it yourself or run watchfire definition generate and edit the draft.

Ready to go

Get started with Watchfire

Install in seconds. Define tasks. Let agents ship code for you.

Download for macOS

Available for macOS, Linux, and Windows

install

# Install via Homebrew (macOS)

$brew tap watchfire-io/tap

$brew install --cask watchfire-io/tap/watchfire

# Set up your project and go

$watchfire init

$watchfire task add "Build the login page"

$watchfire start --all

Includes GUI, CLI, and daemon. Also available via Homebrew.

View on GitHub Read the Docs