watchfire-io/watchfire

Better context. Better code. Contribute to watchfire-io/watchfire development by creating an account on GitHub.

57 stars · 3 forks · 1 watchers

README

Better context. Better code.

AI coding agents work best when they have the right context. Watchfire lets you define your project structure, break work into well-scoped tasks, and orchestrate agents that execute with full awareness of your codebase, constraints, and goals. It manages context automatically — so agents stay on track and produce code you'd actually ship.

Install macOS

Homebrew (recommended): brew tap watchfire-io/tap brew install --cask watchfire-io/tap/watchfire # Desktop app (GUI + CLI) brew install watchfire-io/tap/watchfire # CLI & daemon only Script: curl -fsSL https://raw.githubusercontent.com/watchfire-io/watchfire/main/scripts/install.sh | bash Linux curl -fsSL https://raw.githubusercontent.com/watchfire-io/watchfire/main/scripts/install.sh | bash Homebrew also works on Linux: brew tap watchfire-io/tap && brew install watchfire-io/tap/watchfire Windows irm https://raw.githubusercontent.com/watchfire-io/watchfire/main/scripts/install.ps1 | iex

How It Works

Key Features 🎯 Context Management Define your project once. Watchfire feeds agents the right specs, constraints, and codebase context — no copy-pasting prompts. 📋 Structured Workflow Break big projects into tasks with clear specs. Agents tackle them in order, each in an isolated git worktree branch. 🚀 Scale with Confidence Run agents across multiple projects in parallel. Monitor live terminal output, review results, and merge — from TUI or GUI.

Agent Modes

Mode Description

Chat Interactive session with the coding agent

Task Execute a specific task from the task list

Start All Run all ready tasks sequentially

Wildfire Autonomous loop: execute tasks, refine drafts, generate new tasks

Generate Definition Auto-generate a project definition from your codebase

Generate Tasks Auto-generate tasks from the project definition

MCP Server Watchfire is also an MCP server: any MCP-capable coding agent can use it as a factory for other agents. The outer agent plans and reviews; Watchfire manufactures the code in sandboxed, git-worktree-isolated runs and merges the results. The server is local-only by construction — its only transport is stdio, spawned by the MCP client on this machine. It never opens a listening socket and is not reachable from outside the host. Quickstart Register the server with your client in one command: watchfire mcp install claude-code # Claude Code watchfire mcp install codex # OpenAI Codex (~/.codex/config.toml) watchfire mcp install gemini # Gemini CLI (~/.gemini/settings.json) watchfire mcp install opencode # opencode (~/.config/opencode/opencode.json) watchfire mcp install copilot # Copilot CLI (~/.copilot/mcp-config.json)

watchfire mcp install # interactive picker (the five above + Custom) Installers merge into existing config files (never overwrite) and are idempotent — re-running updates or no-ops. If a client isn't installed or its config can't be parsed, the manual snippet is printed instead. For any other MCP client, print the generic snippet: watchfire mcp install --print { "command": "watchfire", "args": ["mcp", "serve"] } The factory loop The server exposes Watchfire's project, task, run, and inspect surfaces as 18 MCP tools. The canonical loop for an outer agent:

create_task — file a task with a prompt + acceptance criteria run_task — launch a sandboxed agent on it in an isolated worktree wait_for_task — block until the run completes (on timed_out: true, call it again) get_task — check success / failure_reason — done means the agent stopped, not that it succeeded get_task_diff — review exactly what changed, then iterate with follow-up tasks

Creating a task never starts it: status ready queues a task for run_all (and lets an in-flight run_all/wildfire chain pick it up), while run_task is what starts one now. Watchfire runs at most one agent per project — the run tools refuse rather than queue while one is busy, so use wait_for_task or stop_agent first. The rest of the catalog: list_projects, get_project, list_tasks, update_task, delete_task, run_all, start_wildfire, stop_agent, get_agent_status, get_agent_screen, get_insights, list_logs, get_log. Read-only mode watchfire mcp serve --read-only serves only the 10 observation tools (projects, tasks, diffs, screens, insights, logs, agent status) — no task creation, editing, or agent control. The write and run tools aren't merely refused: they are never registered, so they don't appear in tools/list at all. Useful for dashboards or less-trusted callers. A note on recursion A Watchfire-managed agent could itself call the Watchfire MCP server — tasks spawning tasks. This works, but it is not the designed pattern (outer agent → Watchfire is), and an agent that files new tasks on every run can create an unbounded task-spawning loop. Prefer having the outer agent own the loop and review each run's diff before queueing more work.

Build from Source

Build & install

Use it

Components

Component Binary Description

Daemon watchfired Orchestration, PTY management, git workflows, gRPC server, system tray

CLI/TUI watchfire Project-scoped CLI commands + interactive TUI mode

GUI Watchfire.app Electron multi-project client

Development make dev-daemon # Daemon with hot reload make dev-tui # Build and run TUI make dev-gui # Electron GUI dev mode make test # Tests with race detector make test-mcp-e2e # MCP end-to-end test (real binary + real daemon, isolated HOME) make lint # Linting make proto # Regenerate protobuf code Architecture See ARCHITECTURE.md for the full design document. Star History

License Licensed under the Apache License, Version 2.0.

source