watchfire chat

Start an interactive chat session with the coding agent.

Usage

watchfire chat

Description

watchfire chat opens a terminal-attached agent session for free-form conversation. The agent has full access to your project directory but is not assigned a specific task — it runs in the project root rather than an isolated worktree.

This is useful for exploring your codebase, asking questions, making quick edits, or prototyping changes without creating a formal task.

Flags

Flag	Description
--sandbox <backend>	Override the sandbox backend. Valid values: auto, seatbelt, landlock, bubblewrap, none.
--no-sandbox	Shorthand for --sandbox none — disables sandboxing entirely.

Sandbox priority: CLI flag → project setting (project.yaml) → global default (settings.yaml).

Agent Selection

Chat sessions use the project's default agent, falling back to the global default and finally to claude-code. To chat with a different backend, change project.default_agent in project settings or the global default in Watchfire settings before launching.

See Supported Agents for the available backends.

Notes

• The agent runs in the project root directory (not a worktree)
• No task context is injected — the agent operates in free-form mode
• The daemon starts automatically if it's not already running
• watchfire run (with no arguments) provides equivalent functionality

Examples

Spelunk a bug without touching your branch

watchfire chat

Chat runs in the project root, so reads are free but any edits land on your current branch. For investigation that must not touch in-flight work, use a task instead — it runs in an isolated worktree.

Skip the sandbox for a one-off exploration

watchfire chat --no-sandbox

Useful when you need to read paths the sandbox blocks (credentials dirs, .env) for diagnosis. Prefer leaving the sandbox on for normal sessions.

Equivalent using the run command

watchfire run

watchfire run with no arguments is identical to watchfire chat — both open a chat session against the project's resolved agent.

Common pitfalls

• Edits land on your working branch — chat does not use a worktree, so any file changes the agent makes are written to the currently checked-out branch. Fix: close the chat without saving, or run the work as a task — see watchfire task.
• Wrong backend started — chat picks up the project default agent, not whichever CLI you last used. Fix: set default_agent in .watchfire/project.yaml via watchfire configure, or pin a different default at the global level.
• Backend not authenticated — the chat session opens but the agent prints Please run /login or 401. Fix: re-authenticate the backend in its own CLI — see Agent backend not authenticated.