Skip to content

Modes (Build / Plan / Chat)

A mode is a preset that swaps the system prompt and tool list for a chat session. Doable ships three:

Mode Purpose Tools
Build The default. The agent edits files, installs packages, and runs the dev server. All write-capable tools
Plan The agent analyzes the codebase and produces a written plan, but never modifies anything. Read-only tools (read_file, list_dir, grep, fetch)
Chat Free-form Q&A about the project. No tools. Cheapest in tokens. None

Modes are picked from a dropdown in the chat panel. The active mode is stored on the chat row (chats.mode).

Why modes?

  • Safety — Plan mode lets non-developer stakeholders review the agent's intended changes before they touch code.
  • Cost — Chat mode skips the long tool-list system prompt entirely.
  • UX — Different prompts shape the AI's tone (terse vs verbose, code-first vs explainer-first).

Defining custom modes

Workspace admins can add their own modes from Workspace Settings → AI → Modes:

  • Name — display label (e.g. "Refactor", "Docs writer").
  • System prompt — appended to the base prompt.
  • Allowed tools — checkbox list filtered from all available tools.
  • Default model — optionally pin to a specific model.

The configuration is persisted in the mode_tool_config table (see packages/db/migrations/050_mode_tool_config.sql) and consumed by services/api/src/ai/modes/.

How a mode is applied at runtime

When a chat message comes in:

  1. The API loads the chat's mode and the workspace's mode_tool_config.
  2. engine-resolver.ts builds the effective prompt: BASE_PROMPT + MODE_PROMPT + WORKSPACE_OVERRIDE.
  3. The tool loader filters the global tool list by the mode's allow-list.
  4. docore opens (or resumes) the session with that prompt + tool set.

Switching modes mid-conversation creates a fresh session under the hood — the chat history persists, but the agent's working state is reset.

Plan-mode workflow

Plan mode is special enough to have its own UI. When the agent finishes producing a plan:

  • The plan is parsed by services/api/src/ai/plan-parser.ts into a structured list of steps.
  • A "Run plan in Build mode" button appears.
  • Clicking it switches to Build mode and feeds the plan back as the next user message.

This gives a clean review → execute flow that works well for non-developers.

See also