watchfire settings

Configure project settings interactively.

Usage

watchfire configure
watchfire config       # alias

Description

watchfire configure lets you interactively update your project's settings. It presents each configurable option and saves changes to .watchfire/project.yaml.

Global Watchfire settings (the default agent for new projects and custom binary paths) are managed from the GUI Settings panel and persisted to ~/.watchfire/settings.yaml. The CLI configure command only edits the per-project file.

Configurable Settings

Setting	Description	Default
Sandbox mode	Sandbox mechanism for agent processes	auto
Auto-merge	Automatically merge completed task branches to the default branch	true
Auto-delete branch	Delete worktree branches after successful merge	true
Auto-start tasks	Start an agent automatically when a task status is set to ready	true
Default agent	Project default backend (claude-code, codex, opencode, gemini, or copilot)	Inherited from global default
Project color	Hex color used to identify the project in the GUI	—

The Default agent picker writes to default_agent in .watchfire/project.yaml. Leave it unset and Watchfire falls back to the global default agent (and ultimately to claude-code if no default is configured anywhere).

Settings UI (GUI)

The GUI Settings panel exposes both project and global settings, including dedicated controls for agent selection and binary discovery:

• Project default agent — picker that selects which backend the project should prefer
• Per-task agent — pickers in the task editor for overriding the agent on individual tasks
• Global default agent — used by any project that does not set its own default_agent
• Custom binary paths — per-backend path override for claude, codex, opencode, gemini, and copilot when Watchfire cannot locate the binary on PATH

When a custom path is set, Watchfire uses it instead of searching PATH or known install locations. See Supported Agents for the resolution order Watchfire applies to each backend.

Effective Agent Resolution

When Watchfire launches a session it picks the backend in this order:

1. task.agent (if defined on the task YAML)
2. project.default_agent (from .watchfire/project.yaml)
3. Global default agent (from ~/.watchfire/settings.yaml)
4. claude-code

This means project and global settings only apply when a task does not pin its own agent.

Notes

• Project settings are stored in .watchfire/project.yaml
• Global settings (default agent, custom binary paths) are stored in ~/.watchfire/settings.yaml
• Changes take effect immediately for new agent sessions
• Running agent sessions are not affected by settings changes
• Initial project settings are configured during watchfire init

Examples

Walk through every project setting

watchfire configure

Opens the interactive prompt for each row in the configurable-settings table — sandbox mode, auto-merge, auto-delete-branch, auto-start-tasks, default agent, project color. Press Enter to keep the existing value.

Toggle auto-merge for the current project

watchfire config

When prompted for Auto-merge, set it to false if you want completed tasks to stay on their watchfire/<n> branches for review (typically paired with the GitHub auto-PR adapter). All other settings keep their existing values.

What project.yaml looks like after configuring

project_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: my-project
default_agent: codex
sandbox: auto
auto_merge: false
auto_delete_branch: true
auto_start_tasks: true

The CLI rewrites these fields in place. Other project keys (like definition and next_task_number) are preserved.

Common pitfalls

• Looking for global settings here — watchfire configure only edits the per-project file. Fix: global default agent and custom binary paths live in ~/.watchfire/settings.yaml and are managed from the GUI Settings panel.
• Running session not affected — flipping auto_merge mid-task does not retroactively merge the running task. Fix: settings only take effect for new agent sessions; finish or cancel the active session first.
• Default agent picker shows unexpected backends — only claude-code, codex, opencode, gemini, and copilot are valid. Fix: if your shell has a custom binary, set the path in GUI Settings → Agents instead of inventing a new agent name.