Daemion docs

What are modes?

A mode is a named execution configuration for a thread. Each mode sets a system prompt injection, an optional tool filter, and an approval gate. Threads start in the default mode (plan) and can switch modes mid-conversation.

Modes are data, not code. The AgentMode interface in src/gateway/modes.ts defines the shape. Built-in modes ship with Daemion; custom modes can be added to the registry.

Built-in modes

Two modes ship with Daemion:

Plan mode (default)

The agent explores, reasons, and presents a structured plan. It cannot write files, execute commands, or make changes. The user reviews the plan and approves before anything runs.

text

name: plan label: Plan color: #f59e0b requiresApproval: true allowedTools: Read, Glob, Grep, WebFetch, WebSearch

System prompt injection: the agent is told to present steps, files affected, and expected outcome — then wait.

Act mode

Full tool access. No approval gate. The agent executes directly. Use this when you trust the plan and want the agent to proceed without confirmation steps.

text

name: act label: Act color: #3b82f6 requiresApproval: false allowedTools: (all tools available)

No system prompt injection — the agent’s base system prompt and soul apply without additional constraints.

How modes work

When a thread is in a mode, the gateway:

  1. Injects the mode’s systemPrompt at the front of the agent’s context
  2. Filters available tools to allowedTools if set (no filter = all tools allowed)
  3. If requiresApproval is true, pauses execution after the agent’s response and waits for user confirmation before proceeding

The mode’s color is surfaced in the PWA as a visual indicator so users always know which mode is active.

Switching modes

Pass the mode field when posting a turn:

bash

curl -X POST http://localhost:3001/chat
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{“thread_id”: “thr_01abc123”, “content”: “Now go ahead and implement it.”, “mode”: “act”}’

The mode applies to that turn and persists as the thread’s active mode until changed.

Custom modes

Custom modes extend the built-in set. Define them in daemion.yaml or create them via the API. A custom mode follows the same shape as built-in modes:

yaml

name: review label: Review color: “#10b981” description: “Read-only review pass. No writes, no approvals needed.” systemPrompt: “You are reviewing code for correctness and style. Read only. Do not make changes.” allowedTools:

  • Read
  • Grep
  • Glob requiresApproval: false

Custom modes are resolved at runtime via resolveMode(). If an unknown mode name is passed, the gateway falls back to plan.

Q What is the default mode?
Plan. All threads start in plan mode unless overridden in the POST body. This means the agent will explore and present a plan before doing anything — the safest default for most workflows.
Q Can I create a mode with no tool restrictions?
Yes. Set allowedTools to undefined or omit it. This is what act mode does. The agent gets all tools the gateway exposes.
Q Does requiresApproval block the entire thread?
It pauses the thread's execution after the agent's response. The agent has already produced its plan or output — the approval gate prevents it from taking further action until the user confirms. Other threads are unaffected.
Q How does Plan mode relate to the soul-building flow?
They are independent. The soul-building onboarding flow fires on first conversation when no soul file exists. Plan/Act mode is a runtime execution control. Both can be active at the same time.
Unknown mode names fall back to plan

If you pass a mode name that does not exist in the built-in list or custom mode registry, the gateway calls resolveMode() which silently falls back to plan. Check the gateway logs if a mode doesn’t behave as expected — the name may have a typo.

For the thread execution API and setting modes programmatically, see Agents and Identity API.