Frequently asked questions.

Two things: a supported OS (macOS, Linux, or Windows) and at least one agent CLI you’ve signed into — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot CLI, or Cursor Agent. Watchfire does not bundle a model; it drives whichever CLI you already use. Sign in through that CLI’s normal flow first, then point Watchfire at it. Installation guide.

The recommended path is Homebrew. Run brew tap watchfire-io/tap then brew install --cask watchfire-io/tap/watchfire for the GUI + CLI, or brew install watchfire-io/tap/watchfire for just the CLI and daemon. A Universal .dmg is also available from GitHub Releases. Full install instructions.

Use the AppImage or .deb from GitHub Releases for the full GUI + CLI, or run the install script for just the CLI and daemon: curl -fsSL https://raw.githubusercontent.com/watchfire-io/watchfire/main/scripts/install.sh | bash. Watchfire auto-detects the best sandbox backend — Landlock on kernel 5.13+, Bubblewrap on older kernels. Linux install details.

Yes — the .exe installer bundles the GUI, CLI, and daemon. There is one caveat: Windows currently runs without sandboxing. Agent processes are not isolated from the rest of the system, so for security-sensitive work prefer macOS or a recent Linux kernel. See /security for the platform matrix.

Inside a repo you already use, run watchfire init. That creates a .watchfire/ directory with a project.yaml, adds the directory to .gitignore, and walks you through naming the project, picking a default agent, and answering a few yes/no settings (auto-merge, auto-delete branch, auto-start tasks). Then add a task with watchfire task add or let watchfire wildfire generate them. Quick start walkthrough.

The daemon (watchfired) is the single orchestrator: it spawns agent PTYs, manages git worktrees, tracks task state, and serves gRPC. The CLI, TUI, and GUI are all thin clients that talk to that daemon — they show different UIs over the same state, so you can mix them on the same machine and they stay in sync. Architecture overview.

Chat is an interactive session for exploration. Task runs one specific task from the task list. Start All sequentially runs every ready task. Wildfire is the autonomous loop — it executes ready tasks, refines drafts, and generates new tasks from the project definition until you stop it. Use Chat for prototyping, Task or Start All when you’ve written tasks yourself, and Wildfire for longer hands-off runs. Agent modes reference.

Every task runs in its own worktree under .watchfire/worktrees/<n>/ on a dedicated watchfire/<n>branch. That means parallel tasks never touch each other’s files, a failed or half-done run never pollutes main, and a finished task can be reviewed like any other branch before merging. Worktree isolation.

On macOS and Linux, every agent process runs inside a platform sandbox — Seatbelt (sandbox-exec) on macOS, Landlock on Linux 5.13+ with Bubblewrap as a fallback — that denies read and write access to ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, ~/.npmrc, and .git/hooks by default. Enforcement is at the kernel level, so it does not rely on the agent being well-behaved. Sandboxing details.

Only when the task completes successfully and auto_mergeis enabled for the project (it’s a per-project setting you chose at watchfire init). If auto-merge is off, the task lands on its branch and waits for you to review and merge it yourself. Either way, nothing rewrites your default branch silently.

Yes. The daemon watches .watchfire/tasks/and reacts to edits in real time — changing a task from draft to ready in your editor will auto-start an agent if auto_start_tasks is on. This is how the YAML-as-source-of-truth design holds together regardless of which client you use.

A task is a small YAML file at .watchfire/tasks/<n>.yaml with at minimum a title, a prompt, acceptance criteria, and a status. The daemon fills in IDs, timestamps, and outcome fields after a run completes. Files are plain text by design — you can edit them in your editor, diff them with git, and treat them like any other source-controlled artefact (even though .watchfire/ is gitignored by default). Project and task schemas.

draftmeans “don’t run me yet” — safe to edit. Flipping a task to ready tells the daemon it can be executed; if auto_start_tasks is on, an agent will pick it up immediately, otherwise it sits in the queue for Start All or Wildfire. done marks completion — check the success flag to see whether it finished or bailed.

The definition is a free-form description of what the project is and how the agent should approach it — tech stack, layout conventions, code style, gotchas. The daemon injects it into the agent’s system prompt at launch. You don’t need to write one yourself: watchfire definition generate will draft it for you by reading the repo, and you can keep editing it after.

watchfire generate (and the generate phase of wildfire) asks the agent to propose tasks against the project definition. Tasks land as draft YAML files, so you can read them, edit them, delete the bad ones, and promote the good ones to ready. The agent never quietly executes a task it generated — the promotion step is yours.

Wildfire alternates between three phases until you stop it or the queue is empty: execute any ready tasks, refine draft tasks (sharpening the prompt and acceptance criteria), and generatenew draft tasks from the definition. It’s the closest Watchfire gets to “set it and walk away,” and the worktree + sandbox keep the blast radius bounded the whole time. Wildfire command reference.

Six: Claude Code (Anthropic), OpenAI Codex CLI, opencode, Gemini CLI (Google), GitHub Copilot CLI, and Cursor Agent CLI (the headless one, distinct from the in-editor agent). Each one keeps its own auth and config, and Watchfire sets up per-session homes so sessions stay isolated from each other. Supported agents reference.

Yes — the default agent is a per-project setting in project.yaml. One project can use Claude Code, another Codex, another opencode. The daemon handles them concurrently, so a slow Codex session won’t block a Claude Code session in another repo.

Wherever that agent CLI normally keeps them — Watchfire doesn’t store or relay model credentials. Sign in once through the agent’s own login flow (e.g. claude CLI login, codex login, gh auth login), and Watchfire reuses that setup from ~/.claude/, ~/.codex/, ~/.config/opencode/, etc. Security model.

Yes — change default_agent in project.yaml (or via watchfire settings) and new sessions will use the new backend. In-flight sessions keep running on their original backend until they finish.

Indirectly — through the agent CLI. opencode is the most flexible here: you point it at any provider it supports and Watchfire drives opencode normally. Claude Code, Codex, Gemini CLI, and Copilot CLI are tied to their vendor’s models.

Watchfire itself doesn’t phone home — the daemon and every client are local-first with no Watchfire-operated server in the path. The agent backend you configure still talks to its own model provider exactly the way it would if you ran it directly; that traffic is between you and that vendor. Privacy · Security.

In your OS keyring — Keychain on macOS, Secret Service on Linux, Credential Manager on Windows — with a clearly-flagged file-store fallback for hosts without a keyring backend. The IntegrationsService.Save gRPC is write-only on the wire: clients can replace secrets but never read existing values back over RPC. Where Watchfire keeps your secrets.

Put them in .watchfire/secrets/instructions.md — a Markdown file the agent sees read-only via its system prompt. The directory is gitignored by default; it’s your file, not ours. Use it for “the production database URL is X,” “run migrations against this Stripe test key,” and similar setup notes. Secrets & setup instructions.

No. On macOS and Linux, the platform sandbox denies read and write access to ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, and ~/.npmrc for every agent process. Enforcement is at the kernel level, so it does not rely on the agent being well-behaved.

Windows doesn’t expose a kernel primitive equivalent to Seatbelt or Landlock that we can use without major caveats, so Watchfire runs agent processes unsandboxed there today. For security-sensitive work prefer macOS or a recent Linux kernel. This is called out plainly in the install docs and on /security.

Three things, in layers: the sandbox (no access to credentials or directories outside the project), the worktree (writes land on a watchfire/<n> branch, not on your default branch), and you (nothing merges without a review you triggered, unless you turned auto-merge on). Restart protection also caps runaway loops before they burn budget. Threat model.

Aider is itself an agent — a tight conversational pair-programming CLI. Watchfire is an orchestrator that runs the agent CLI you already trust (including options Aider doesn’t replace) inside a per-task worktree and a platform sandbox. Pick Aider for a single turn-shaped conversation; pick Watchfire for task-shaped, isolated, parallel work. Watchfire vs Aider.

You can — and you should, for one-off prompts in a repo you already have open. Watchfire adds three things over the raw CLI: per-task git worktrees so failed runs never touch main, a platform sandbox that blocks ~/.ssh and credential stores, and parallelism across projects from one daemon. Same agent, safer boundary. Watchfire vs raw CLI.

Cursor’s agent mode lives inside the editor — great for short edits you watch happen. Watchfire is terminal-first and task-shaped: a written prompt, a worktree, a transcript you can review later. The two coexist; Cursor’s headless cursor-agentCLI is also a Watchfire backend, so you can orchestrate Cursor’s models in the worktree-isolated flow. Watchfire vs Cursor agents.

Devin-style products are vendor-hosted: code, prompts, and credentials live on their infrastructure. Watchfire is the local equivalent — your laptop is the runtime, the worktrees and sandboxes live on disk, and you choose the agent CLI on the other end. Pick a cloud agent for hands-off hosted tickets; pick Watchfire when the code or prompts can’t leave the machine. Watchfire vs Devin.

Copilot Workspace is hosted, plan-first, and tightly coupled to GitHub — issues in, PRs out. Watchfire runs on your machine, keeps the code local, and lets you choose the agent and model freely (including GitHub Copilot CLI as one of the backends). Pick Copilot Workspace if your workflow is github.com-centric and you want hosted execution; pick Watchfire for local-first, multi-agent orchestration. Watchfire vs Copilot Workspace.

Watchfire itself is free. You pay whatever your chosen agent CLI’s model costs — the Claude API for Claude Code, the OpenAI API for Codex, etc. There is no subscription, no per-task fee, no seat licence, and no Watchfire-operated server charging in the background.

Apache License 2.0 for the daemon, CLI/TUI, and GUI. Full source and the LICENSE file live at github.com/watchfire-io/watchfire.

Yes — Apache 2.0 explicitly permits commercial use, modification, distribution, and patent grants. Use it in your company, your products, your client work, your closed-source repos. Read the full LICENSE if you want the legal version, but the short version is: there’s no commercial-use carve-out.

Run watchfired --foreground so stderr lands in your terminal. Two common culprits: another process is already on 127.0.0.1:8765 (set a different ListenAddr or stop the conflict), or a stale ~/.watchfire/daemon.yaml with a live-but-unrelated PID (delete it and re-run watchfire daemon start). Full daemon-startup runbook.

Run watchfire daemon status first. If it reports the daemon isn’t running, start it with watchfire daemon start. If it reports a PID but the CLI still can’t connect, the recorded PID is stale — run watchfire daemon stop then watchfire daemon start to clear it. Connection-refused runbook.

The GUI launches watchfired itself by walking PATH and then a couple of standard install locations. If none resolve, the GUI surfaces the connection error. Check which watchfired from a normal terminal; if nothing comes back, reinstall (Homebrew is the easy path on macOS). If the binary exists, start the daemon manually before opening the app. GUI runbook.

Use watchfire task stop <n> to clear the in-progress flag, then inspect the worktree under .watchfire/worktrees/<n> for partial work. You can resume by flipping the task back to ready, or set success: false with a failure_reason if the run is unrecoverable. Stuck-task runbook.

Auto-merge intentionally bails on conflicts rather than guessing. Open the worktree, resolve conflicts the way you would for any other branch, then merge manually. Watchfire won’t retry silently behind your back — the worktree and branch stay until you decide what to keep. Merge-failure runbook.

Wildfire keeps generating and executing while there are ready tasks (or drafts to refine, or definition gaps to fill). Cap it with the iteration / time limits in watchfire wildfire --help, or stop it interactively from the TUI/GUI. Restart protection already caps obvious runaway loops, but Wildfire’s job is to keep working — you tell it when to stop. Wildfire-loop runbook.