Skip to main content
An agent mode changes the instructions and tools available to the current chat session. It does not change your approval mode. A tool still asks for approval when the active approval policy requires it.

​
Choose a mode

In VS Code, use the mode control beside the composer or run the matching slash command:

​
Cycle with Shift+Tab

Press Shift+Tab while the composer is focused to move through the modes supported by the local runtime. The same shortcut works in the terminal UI. The cycle is:

​
Act mode

Act mode is the normal implementation mode. The agent can read and edit files, run shell commands, build and flash firmware, use serial tools, and complete other project work. Act mode does not expose the dedicated Debug-mode tool set. Switch to Debug when the task needs GDB state inspection, managed debugger servers, hardware automation scripts, instruction trace, or a coverage capture. Use Act mode when:
  • the requested change is small and already well specified;
  • you approved a plan and want the agent to implement it;
  • a software-only problem can be reproduced with normal tests or build commands;
  • you need an ordinary build, flash, or serial workflow without an interactive hardware investigation.
Act mode permits changes, but approval rules and safety checks still apply. For example, a flash operation can require confirmation, and .embedderignore can block an edit.

​
Plan mode

Plan mode keeps the project read-only while the agent investigates the request. It can inspect files, documents, schematics, diagnostics, static analyzer configuration, saved traces, serial history, and hardware status. It cannot use the shell or change project files. The only writable file is the plan for that session. Embedder normally stores plans under:
If the project directory is not writable, Embedder stores the plan in the project’s virtual data directory under the Embedder application directory. When the plan is ready, Embedder opens it for review. You can:
  • request changes to the approach;
  • edit the plan yourself;
  • approve it for implementation.
Approving the plan starts the implementation turn in Act mode. Until you approve it, Plan mode cannot modify the project.

​
Debug mode

Debug mode includes Act-mode editing and command access, then adds the hardware debugging tools withheld from Act mode. Entering Debug mode also injects a current hardware status snapshot so the agent can see configured providers, connected devices, and managed debugger availability. The expected workflow is:
  1. Observe the code, buffered output, debugger state, and available hardware.
  2. Record explicit hypotheses.
  3. Probe one hypothesis with the least invasive useful experiment.
  4. Verify the root cause and the fix against the original symptom.
Hardware scripts live under .embedder/hardware/. Longer investigations use a case directory under .embedder/hardware/cases/ so findings and hypothesis verdicts survive context compression and session restarts. Use Debug mode for faults, timing failures, peripheral behavior, power problems, and bugs that require live target evidence. Stay in Act mode for compile failures or software-only defects that a normal test can reproduce.

​
Modes are session-scoped

Each chat session keeps its own mode. Changing the mode in one editor chat does not change another open session. A queued prompt also keeps the mode that was selected when you sent it. If you queue a prompt in Act mode and switch the visible session to Plan mode, that queued prompt still runs with its captured Act-mode setting. Review queued work before changing workflows. Your approval mode is separate. Switching from Plan to Act, for example, does not enable automatic approval or clear your allowlist.
Last modified on August 24, 2026