CLI / TUI (watchfire)

The CLI/TUI is the primary interface for developers. A single binary (watchfire) operates in two modes: CLI commands for scripting and automation, and TUI mode for interactive work. It's project-scoped — run from within a project directory.

CLI Commands

Global

Command	Alias	Description
watchfire		Start TUI
watchfire version	--version, -v	Show version (all components)
watchfire help	-h	Show help
watchfire update		Update all components
watchfire init		Initialize project in current directory

Project Lifecycle

Command	Alias	Description
watchfire define	def	Edit project definition in $EDITOR
watchfire configure	config	Configure project settings (interactive)

Task Management

Command	Alias	Description
watchfire task list	task ls	List tasks (excludes deleted)
watchfire task list --deleted		List soft-deleted tasks
watchfire task add		Add new task (interactive)
watchfire task <taskid>		Edit task (interactive)
watchfire task delete <taskid>	task rm <taskid>	Soft delete task
watchfire task restore <taskid>		Restore soft-deleted task

Execution

Command	Alias	Description
watchfire run		Start chat mode
watchfire run <taskid>		Run specific task
watchfire run all		Run all ready tasks sequentially
watchfire plan		Generate tasks from project definition
watchfire generate	gen	Generate project definition
watchfire wildfire	fire	Autonomous three-phase loop

Daemon

Command	Alias	Description
watchfire daemon start		Start the daemon
watchfire daemon status		Show daemon info
watchfire daemon stop		Stop the daemon

watchfire init Flow

1. Check for git → if missing, initialize git repo
2. Create .watchfire/ directory structure
3. Create initial project.yaml
4. Append .watchfire/ to .gitignore
5. Commit .gitignore change
6. Prompt for the coding agent (Claude Code, Codex, opencode, Gemini, Copilot)
   — seeded into project.default_agent
7. Prompt for project definition (optional)
8. Prompt for project settings
9. Save project.yaml
10. Register project in ~/.watchfire/projects.yaml

The agent prompt only appears when the global default is set to "Ask per project" (or unset). If a global default is configured, init skips the prompt and uses it. See the Supported Agents doc for backend-specific setup.

TUI Mode

Launch by running watchfire with no arguments. The TUI provides a split-view interface:

┌──────────────────────────────────────────────────────────────────────┐
│ ● project-name  Tasks | Definition | Settings    Chat | Logs  ● Idle│
├────────────────────────────────┬─────────────────────────────────────┤
│  Task List                     │  Agent Terminal / Logs              │
│                                │                                     │
│  Draft (2)                     │  > Starting session...              │
│    #0001 Setup structure       │                                     │
│    #0004 Add authentication    │  > Working on task...               │
│      [codex]                   │                                     │
│                                │                                     │
│  Ready (1)                     │                                     │
│  ● #0002 Implement login [▶]  │                                     │
│                                │                                     │
│  Done (2)                      │                                     │
│    #0003 Create schema   ✓    │                                     │
│    #0005 Add tests       ✓    │                                     │
├────────────────────────────────┴─────────────────────────────────────┤
│ Ctrl+q quit  Ctrl+h help  Tab switch panel           a add  s start │
└──────────────────────────────────────────────────────────────────────┘

A compact agent badge (e.g. [codex]) appears next to a task title when its agent field is set and differs from the project default. Tasks that defer to the project default show no badge, keeping the list visually quiet for the common case.

Navigation

Input	Action
Tab	Switch between left/right panels
j/k or ↓/↑	Move up/down in lists
h/l or ←/→	Switch tabs
1/2/3	Switch left panel tabs
Enter	Select/edit item
Esc	Close overlay / cancel
Ctrl+q	Quit
Ctrl+h	Help overlay

Task Actions

When the task list is focused:

Key	Action
a	Add new task
e / Enter	Edit selected task
s	Start task (set to Ready + start agent)
r	Move task to Ready
t	Move task to Draft
d	Mark done
x	Delete (soft)

Left Panel Tabs

Tab	Content
Tasks	Task list grouped by status. Tasks with a per-task agent override show an agent badge next to the title.
Definition	Project definition (press e to edit in $EDITOR)
Settings	Git config, automation toggles, and a coding agent selector that cycles through the registered backends (project default).

Right Panel Tabs

Tab	Content
Chat	Live agent terminal output
Logs	Past session logs per task. Formatted transcripts render for all supported backends (Claude Code, Codex, opencode, Gemini, Copilot), falling back to PTY scrollback when no transcript is available.

Task Form

The Add / Edit Task overlay includes an agent field — a cycling selector below the existing fields. The first option, Project default (<name>), maps to the empty string and keeps the task on whatever the project is configured for. The remaining options are the registered backends. Saving the form writes the chosen value to the task's agent field.

TUI Features

• Mouse support (click, scroll, drag divider)
• Vim-like + arrow key navigation
• Resizable panels (40/60 default split)
• Real-time streaming from daemon
• Context-sensitive keyboard shortcuts
• Agent issue banners (auth errors, rate limits)
• Auto-reconnect on daemon disconnection