# 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): Better context. Better code. Watchfire turns clear specs into scoped tasks, then lets Claude Code, Codex, opencode, Gemini CLI, or GitHub Copilot CLI build them in sandboxed git worktrees.
- [Installation](https://watchfire.io/docs/installation): Install Watchfire on macOS, Linux, or Windows.
- [Supported Agents](https://watchfire.io/docs/concepts/supported-agents): Watchfire supports Claude Code, OpenAI Codex, opencode, Gemini CLI, and GitHub Copilot CLI. Learn what to install, how authentication works, and how Watchfire finds each backend.
- [Quick Start](https://watchfire.io/docs/quickstart): Get up and running with Watchfire in minutes. Initialize a project and let Wildfire mode handle the rest.
- [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): Each task runs in its own git worktree on a dedicated branch — isolating it from your main working tree, and (across projects) from any other agent running concurrently.
- [Sandboxing](https://watchfire.io/docs/concepts/sandboxing): Watchfire sandboxes coding agents using platform-specific backends — Seatbelt on macOS, Landlock or Bubblewrap on Linux — to restrict filesystem access and limit 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): A two-way integrations layer — outbound adapters for webhooks, Slack, Discord, and GitHub auto-PR, plus an inbound HTTP server with signature verification, OAuth bot tokens, and multi-host parity.
- [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): Initialize a new Watchfire project in the current directory.
- [watchfire task](https://watchfire.io/docs/commands/task): Manage tasks — add, list, edit, delete, and restore tasks in your project.
- [watchfire run](https://watchfire.io/docs/commands/run): Run an agent in chat mode, execute a single task, or run all ready tasks.
- [watchfire chat](https://watchfire.io/docs/commands/chat): Start an interactive chat session with the coding agent.
- [watchfire wildfire](https://watchfire.io/docs/commands/wildfire): Start the autonomous wildfire mode — execute, refine, and generate tasks in a continuous loop.
- [watchfire generate](https://watchfire.io/docs/commands/generate): Generate a project definition or task list using a coding agent.
- [watchfire daemon](https://watchfire.io/docs/commands/daemon): Manage the Watchfire daemon — start, stop, and check status.
- [watchfire definition](https://watchfire.io/docs/commands/definition): Edit the project definition that guides agent behavior.
- [watchfire settings](https://watchfire.io/docs/commands/settings): Configure project settings interactively, including agent selection and custom binary paths.
- [watchfire integrations](https://watchfire.io/docs/commands/integrations): Manage Watchfire's outbound delivery adapters and inbound HTTP integrations from the command line.
- [watchfire status](https://watchfire.io/docs/commands/status): Show current project status including active agents and task progress.
- [watchfire metrics](https://watchfire.io/docs/commands/metrics): Manage per-task metrics — backfill historical records so Insights have something to chart.
- [watchfire update](https://watchfire.io/docs/commands/update): Self-update Watchfire from GitHub Releases.
- [How Watchfire compares](https://watchfire.io/docs/compare): Honest comparison of Watchfire to adjacent AI coding tools — Aider, Cursor agents, Claude Code on its own, GitHub Copilot Workspace, and Devin/Codegen-style autonomous agents.
- [Contributing](https://watchfire.io/docs/contributing): How to contribute to Watchfire — code, docs, bug reports, ideas, and community help.
- [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): Common Watchfire failure modes and copy-paste fixes — daemon won't start, GUI can't reach watchfired, stuck tasks, dirty merges, sandbox denials, and where to ask for help.
- [Tips & Best Practices](https://watchfire.io/docs/tips): Hard-won advice for writing tasks agents finish, sizing work, picking modes, keeping merges clean, and getting the most out of Beacon — distilled from running Watchfire across real projects.
- [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 of every TUI keybinding and the keyboard shortcuts available in the Watchfire GUI.
- [Roadmap](https://watchfire.io/docs/roadmap): A snapshot of where Watchfire is heading after Flare — 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.