# watchfire-io/watchfire architecture

> Architecture diagram of the GitHub repository watchfire-io/watchfire, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/watchfire-io/watchfire
- Repository: https://github.com/watchfire-io/watchfire

## Overview

Watchfire is a local-first AI coding-agent orchestrator: users register projects, define context and tasks, launch isolated agent runs, then monitor and review results. Its desktop, CLI/TUI, Telegram bridge, and MCP server expose overlapping controls over a daemon that owns project, task, agent, and integration services. The README documents the major workflows; sampled source confirms selected daemon, GUI, and MCP relationships. Unsampled subsystem links are omitted where their callers could not be verified.

Main entry points: [`internal/daemon/server/server.go`](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/server/server.go) (Daemon RPC Server), [`internal/daemon/agent/manager.go`](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/manager.go) (Agent Manager), [`internal/daemon/task/manager.go`](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/task/manager.go) (Task Manager), [`internal/mcpserver/server.go`](https://github.com/watchfire-io/watchfire/blob/main/internal/mcpserver/server.go) (MCP Tool Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interfaces"]
  node_desktop["Desktop Views<br/>[App.tsx]"]
  node_gui_rpc["GUI gRPC Client<br/>[grpc-client.ts]"]
  node_cli["CLI Commands<br/>[root.go]"]
  node_tui["Terminal UI<br/>[tui.go]"]
end

subgraph group_core["Daemon Core"]
  node_daemon["Daemon RPC Server<br/>[server.go]"]
  node_project["Project Manager<br/>[manager.go]"]
  node_task["Task Manager<br/>[manager.go]"]
  node_config[("Project and Task Files<br/>[tasks.go]")]
end

subgraph group_agents["Agent Execution"]
  node_agent["Agent Manager<br/>[manager.go]"]
  node_backends["Agent Backends<br/>[backend.go]"]
  node_worktree["Git Worktrees<br/>[worktree.go]"]
  node_terminal["Live Agent Sessions<br/>[process.go]"]
end

subgraph group_remote["Remote Control"]
  node_telegram["Telegram Bridge<br/>[bridge.go]"]
  node_integrations["Inbound Integrations<br/>[server.go]"]
  node_relay["Event Relay<br/>[dispatcher.go]"]
  node_mcp["MCP Tool Server<br/>[server.go]"]
end

subgraph group_insight["Review and Context"]
  node_insights["Insights and Digests<br/>[project.go]"]
  node_git_review["Diff and Branch Review<br/>[diff.go]"]
  node_definition["Project Context<br/>[definition.go]"]
end

node_user(("Operator"))
node_mcp_client(("MCP Client Agent"))
node_telegram_service(("Telegram Service"))
node_chat_services(("Chat and Webhook Services"))

node_user -->|"manages projects"| node_desktop
node_desktop -.->|"requests daemon data"| node_gui_rpc
node_gui_rpc -.->|"sends gRPC"| node_daemon
node_user -->|"runs commands"| node_cli
node_user -->|"supervises runs"| node_tui
node_daemon -->|"dispatches project work"| node_project
node_daemon -->|"dispatches task work"| node_task
node_daemon -->|"dispatches agent work"| node_agent
node_project -->|"registers projects"| node_config
node_task -->|"saves tasks"| node_config
node_user -->|"defines context"| node_definition
node_user -->|"creates scoped tasks"| node_task
node_agent -->|"starts agents"| node_backends
node_agent -->|"isolates runs"| node_worktree
node_agent -->|"manages sessions"| node_terminal
node_user -->|"requests factory tools"| node_mcp
node_mcp_client -->|"calls tools"| node_mcp
node_mcp -->|"translates to RPC"| node_daemon
node_user -->|"pairs and supervises"| node_telegram
node_telegram -->|"polls and replies"| node_telegram_service
node_daemon -->|"registers handlers"| node_integrations
node_integrations -.->|"receives events"| node_chat_services
node_daemon -.->|"dispatches notifications"| node_relay
node_user -->|"reviews activity"| node_insights
node_user -->|"reviews agent changes"| node_git_review

click node_desktop "https://github.com/watchfire-io/watchfire/blob/main/gui/src/renderer/src/App.tsx"
click node_gui_rpc "https://github.com/watchfire-io/watchfire/blob/main/gui/src/renderer/src/lib/grpc-client.ts"
click node_cli "https://github.com/watchfire-io/watchfire/blob/main/internal/cli/root.go"
click node_tui "https://github.com/watchfire-io/watchfire/blob/main/internal/tui/tui.go"
click node_daemon "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/server/server.go"
click node_project "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/project/manager.go"
click node_task "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/task/manager.go"
click node_config "https://github.com/watchfire-io/watchfire/blob/main/internal/config/tasks.go"
click node_agent "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/manager.go"
click node_backends "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/backend/backend.go"
click node_worktree "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/worktree.go"
click node_terminal "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/process.go"
click node_telegram "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/telegram/bridge.go"
click node_integrations "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/echo/server.go"
click node_relay "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/relay/dispatcher.go"
click node_mcp "https://github.com/watchfire-io/watchfire/blob/main/internal/mcpserver/server.go"
click node_insights "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/insights/project.go"
click node_git_review "https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/diff/diff.go"
click node_definition "https://github.com/watchfire-io/watchfire/blob/main/internal/cli/definition.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_gui_rpc,node_cli,node_tui,node_mcp_client toneBlue
class node_daemon,node_project,node_task,node_config toneAmber
class node_agent,node_backends,node_worktree,node_terminal,node_chat_services toneMint
class node_telegram,node_integrations,node_relay,node_mcp toneRose
class node_insights,node_git_review,node_definition,node_user,node_telegram_service toneIndigo
```

## Components

### User Interfaces

- [Desktop Views](https://github.com/watchfire-io/watchfire/blob/main/gui/src/renderer/src/App.tsx): `gui/src/renderer/src/App.tsx`
- [GUI gRPC Client](https://github.com/watchfire-io/watchfire/blob/main/gui/src/renderer/src/lib/grpc-client.ts): `gui/src/renderer/src/lib/grpc-client.ts`
- [CLI Commands](https://github.com/watchfire-io/watchfire/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Terminal UI](https://github.com/watchfire-io/watchfire/blob/main/internal/tui/tui.go): `internal/tui/tui.go`

### Daemon Core

- [Daemon RPC Server](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/server/server.go): `internal/daemon/server/server.go`
- [Project Manager](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/project/manager.go): `internal/daemon/project/manager.go`
- [Task Manager](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/task/manager.go): `internal/daemon/task/manager.go`
- [Project and Task Files](https://github.com/watchfire-io/watchfire/blob/main/internal/config/tasks.go): `internal/config/tasks.go`

### Agent Execution

- [Agent Manager](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/manager.go): `internal/daemon/agent/manager.go`
- [Agent Backends](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/backend/backend.go): `internal/daemon/agent/backend/backend.go`
- [Git Worktrees](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/worktree.go): `internal/daemon/agent/worktree.go`
- [Live Agent Sessions](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/agent/process.go): `internal/daemon/agent/process.go`

### Remote Control

- [Telegram Bridge](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/telegram/bridge.go): `internal/daemon/telegram/bridge.go`
- [Inbound Integrations](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/echo/server.go): `internal/daemon/echo/server.go`
- [Event Relay](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/relay/dispatcher.go): `internal/daemon/relay/dispatcher.go`
- [MCP Tool Server](https://github.com/watchfire-io/watchfire/blob/main/internal/mcpserver/server.go): `internal/mcpserver/server.go`

### Review and Context

- [Insights and Digests](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/insights/project.go): `internal/daemon/insights/project.go`
- [Diff and Branch Review](https://github.com/watchfire-io/watchfire/blob/main/internal/daemon/diff/diff.go): `internal/daemon/diff/diff.go`
- [Project Context](https://github.com/watchfire-io/watchfire/blob/main/internal/cli/definition.go): `internal/cli/definition.go`

### Other components

- **Operator**
- **MCP Client Agent**
- **Telegram Service**
- **Chat and Webhook Services**

## Connections

- Operator → Desktop Views: manages projects (evidence: `README.md`)
- Desktop Views → GUI gRPC Client: requests daemon data
- GUI gRPC Client → Daemon RPC Server: sends gRPC
- Operator → CLI Commands: runs commands (evidence: `README.md`)
- Operator → Terminal UI: supervises runs (evidence: `README.md`)
- Daemon RPC Server → Project Manager: dispatches project work (evidence: `internal/daemon/server/server.go`)
- Daemon RPC Server → Task Manager: dispatches task work (evidence: `internal/daemon/server/server.go`)
- Daemon RPC Server → Agent Manager: dispatches agent work (evidence: `internal/daemon/server/server.go`)
- Project Manager → Project and Task Files: registers projects (evidence: `internal/daemon/project/manager.go`)
- Task Manager → Project and Task Files: saves tasks (evidence: `internal/daemon/task/manager.go`)
- Operator → Project Context: defines context (evidence: `README.md`)
- Operator → Task Manager: creates scoped tasks (evidence: `README.md`)
- Agent Manager → Agent Backends: starts agents (evidence: `internal/daemon/agent/manager.go`)
- Agent Manager → Git Worktrees: isolates runs (evidence: `README.md`)
- Agent Manager → Live Agent Sessions: manages sessions (evidence: `internal/daemon/agent/manager.go`)
- Operator → MCP Tool Server: requests factory tools (evidence: `README.md`)
- MCP Client Agent → MCP Tool Server: calls tools (evidence: `README.md`)
- MCP Tool Server → Daemon RPC Server: translates to RPC (evidence: `internal/mcpserver/server.go`)
- Operator → Telegram Bridge: pairs and supervises (evidence: `README.md`)
- Telegram Bridge → Telegram Service: polls and replies (evidence: `README.md`)
- Daemon RPC Server → Inbound Integrations: registers handlers (evidence: `internal/daemon/server/server.go`)
- Inbound Integrations → Chat and Webhook Services: receives events
- Daemon RPC Server → Event Relay: dispatches notifications
- Operator → Insights and Digests: reviews activity (evidence: `README.md`)
- Operator → Diff and Branch Review: reviews agent changes (evidence: `README.md`)