# Watchfire

> Better context. Better code. Watchfire turns clear specs into scoped tasks, then lets Claude Code, OpenAI Codex, opencode, Gemini CLI, or GitHub Copilot CLI build them in sandboxed git worktrees.

Watchfire is an open-source orchestrator for AI coding agents. A daemon (`watchfired`) manages projects, tasks, git worktrees, and sandboxed agent sessions; a CLI/TUI and an Electron GUI connect to it over gRPC.

## Docs

- [Watchfire](https://watchfire.io/docs): Watchfire documentation — turn specs into scoped tasks, hand each one to Claude Code, Codex, opencode, Gemini, Copilot, or Cursor in a sandboxed worktree.
- [Installation](https://watchfire.io/docs/installation): Install Watchfire on macOS, Linux, or Windows — desktop installer, Homebrew tap, or build from source. Bundles daemon, CLI, TUI, and GUI.
- [Supported Agents](https://watchfire.io/docs/concepts/supported-agents): Supported agent backends — Claude Code, Codex, opencode, Gemini CLI, Copilot CLI, Cursor Agent. What to install, how to auth, how Watchfire finds each one.
- [Quick Start](https://watchfire.io/docs/quickstart): Watchfire quick start — initialize a project, write your first task, and let Wildfire mode generate, execute, and merge work in minutes.
- [Architecture](https://watchfire.io/docs/concepts/architecture): Understand Watchfire's architecture — a daemon orchestrates coding agents while thin clients connect over gRPC.
- [Projects and Tasks](https://watchfire.io/docs/concepts/projects-and-tasks): Understand Watchfire's project configuration and task lifecycle. Projects and tasks are defined as YAML files.
- [Agent Modes](https://watchfire.io/docs/concepts/agent-modes): Watchfire supports six agent modes — Chat, Task, Start All, Wildfire, Generate Definition, and Generate Tasks.
- [Git Worktree Isolation](https://watchfire.io/docs/concepts/worktrees): Git worktree isolation — every Watchfire task runs in its own worktree on a dedicated branch, isolated from your main tree and from concurrent agents.
- [Sandboxing](https://watchfire.io/docs/concepts/sandboxing): Watchfire sandboxes every agent — Seatbelt on macOS, Landlock or Bubblewrap on Linux — to fence filesystem access and contain blast radius.
- [Secrets & Setup Instructions](https://watchfire.io/docs/concepts/secrets): Give AI agents access to external services, API keys, and environment configuration without hardcoding credentials in task prompts.
- [Integrations](https://watchfire.io/docs/concepts/integrations): Watchfire integrations — outbound webhooks plus Slack, Discord, and GitHub auto-PR adapters, and an inbound HTTP server with HMAC signature verification.
- [Insights & Metrics](https://watchfire.io/docs/concepts/insights): Beacon captures per-task metrics, aggregates them per project and across the fleet, and exports CSV or Markdown reports.
- [watchfire init](https://watchfire.io/docs/commands/init): watchfire init bootstraps a Watchfire project — creates .watchfire/ with project.yaml and tasks/, then registers the directory in .gitignore.
- [watchfire task](https://watchfire.io/docs/commands/task): watchfire task is the full task CRUD — add, list, edit, reorder, delete, restore, and start tasks from the YAML files in .watchfire/tasks/.
- [watchfire run](https://watchfire.io/docs/commands/run): watchfire run is the unified entry point for agent sessions — chat with no task, execute a single task by number, or burn through every ready task.
- [watchfire chat](https://watchfire.io/docs/commands/chat): watchfire chat opens a free-form agent session in the project root, no task or worktree — useful for codebase exploration, quick edits, and prototyping.
- [watchfire wildfire](https://watchfire.io/docs/commands/wildfire): watchfire wildfire runs the autonomous loop — execute ready tasks, refine drafts, and generate new tasks until the project queue is exhausted.
- [watchfire generate](https://watchfire.io/docs/commands/generate): watchfire generate hands off to an agent to draft a project definition or break the work into a queue of ready tasks, in one shot or interactively.
- [watchfire daemon](https://watchfire.io/docs/commands/daemon): watchfire daemon manages the watchfired background process — start, stop, restart, and inspect the daemon that orchestrates every agent session.
- [watchfire definition](https://watchfire.io/docs/commands/definition): watchfire definition opens the project definition in your editor — the spec that frames every agent prompt and shapes generated tasks.
- [watchfire settings](https://watchfire.io/docs/commands/settings): watchfire settings opens an interactive form to configure agent backend, custom binary paths, sandbox profile, and other per-project options.
- [watchfire integrations](https://watchfire.io/docs/commands/integrations): watchfire integrations configures outbound webhooks, Slack, Discord, GitHub auto-PR adapters, and the inbound HTTP server that drives the daemon back.
- [watchfire status](https://watchfire.io/docs/commands/status): watchfire status prints a snapshot of the current project — active agent sessions, task queue counts, and the last few lines of every running PTY.
- [watchfire metrics](https://watchfire.io/docs/commands/metrics): watchfire metrics inspects and backfills the per-task metric records that power Beacon — duration, exit code, prompt size, and project rollups.
- [watchfire update](https://watchfire.io/docs/commands/update): watchfire update self-upgrades the daemon, CLI, and TUI to the latest GitHub release — checksum-verified, with rollback if the new binary fails to start.
- [How Watchfire compares](https://watchfire.io/docs/compare): Honest comparison of Watchfire to Aider, Cursor agents, raw Claude Code, GitHub Copilot Workspace, and Devin-style autonomous agents — what each is for.
- [Contributing](https://watchfire.io/docs/contributing): How to contribute to Watchfire — open a PR, write docs, file a bug report or feature idea, run the test suite, and get changes merged.
- [Security](https://watchfire.io/docs/security): Watchfire's threat model — sandbox guarantees, signature verification, secret storage, network exposure, and how to report a vulnerability.
- [Troubleshooting](https://watchfire.io/docs/troubleshooting): Watchfire troubleshooting — fixes for daemon startup, GUI connection, stuck tasks, dirty merges, sandbox denials, and where to file a bug.
- [Tips & Best Practices](https://watchfire.io/docs/tips): Tips and best practices for Watchfire — writing tasks agents finish, sizing work, choosing modes, keeping merges clean, and getting the most from Beacon.
- [Recipes](https://watchfire.io/docs/recipes): End-to-end Watchfire walkthroughs — concrete examples of using tasks, modes, and Wildfire to ship real work, with the exact commands and task definitions.
- [Glossary](https://watchfire.io/docs/glossary): Quick definitions for Watchfire-specific terms — release codenames, agent modes, components, project model, isolation, Beacon vocabulary, and integrations.
- [Keyboard Shortcuts](https://watchfire.io/docs/keyboard-shortcuts): Printable cheat sheet for every Watchfire keybinding — TUI navigation, agent controls, task management, and the GUI shortcuts on macOS and Windows.
- [Roadmap](https://watchfire.io/docs/roadmap): A snapshot of where Watchfire is heading after Forge — what's shipped, what's likely next, and what we're still thinking about.

## Components

- [Daemon (watchfired)](https://watchfire.io/docs/components/daemon): The Watchfire daemon is the backend brain — managing projects, spawning agents, handling git workflows, and serving clients over gRPC.
- [CLI / TUI](https://watchfire.io/docs/components/cli): The Watchfire CLI provides scriptable commands while the TUI offers an interactive split-view interface for managing tasks and monitoring agents.
- [GUI (Watchfire.app)](https://watchfire.io/docs/components/gui): A guided tour of Watchfire.app, the Electron multi-project client for managing tasks, monitoring agents, and reviewing work.

## Optional

- [Source on GitHub](https://github.com/watchfire-io/watchfire): Apache-2.0 licensed.
- [Changelog](https://watchfire.io/docs/changelog): Release notes.