Skip to main content
Start from the Embedder chat in VS Code and associate the workspace with a project. Plan when the implementation is uncertain, then verify build, test, programming, and runtime behavior as separate stages. Replace the examples below with the commands and paths recorded for your project.

​
Set up a project

Embedder opens the project setup flow when the workspace has no selected project. Run /project to select or create a different project later.
1

Select a team and project

Choose an existing project when the workspace already has one. Otherwise, choose Create project and continue to the platform picker.
2

Choose how to describe the hardware

You can start from a catalog platform, add a custom platform, or create the project from schematic files.
  • Catalog platform: search by board, MCU, or manufacturer, select the platform, then name the project.
  • Custom platform: choose + Add platform, enter the platform name, and upload the requested documentation. The chat wizard accepts one or more PDFs and creates a new project with that custom platform.
  • Schematics: choose Upload schematics, name the project, and select the complete schematic source set. Embedder parses the design and matches detected components against its platform and peripheral catalogs.
Custom platform creation appears only when the selected account has access to it.
3

Review peripherals

Add catalog peripherals that are populated on the board. When project schematics or document names imply catalog matches, the picker places those parts on the initial shortlist.See Add and manage peripherals for catalog, custom, and removal behavior.
4

Initialize project instructions

Run /init.
Confirm the detected target, commands, debugger, bench setup, and quality rules. Embedder then creates or refreshes the generated section in the root EMBEDDER.md.

​
Create a project from schematics

The schematic picker accepts KiCad, Eagle, Altium, PADS, Xpedition, and EDIF source formats exposed by the file picker. Supply the complete design set rather than one child sheet. A new-project upload performs these actions:
  1. Creates the project.
  2. Uploads and parses the schematic files.
  3. Stores the parsed schematic data for @sch: references and later design queries.
  4. Adds catalog components when a parsed part value has an unambiguous normalized exact or prefix match.
  5. Opens peripheral suggestions when it finds new catalog matches.
If the parser finds likely peripheral part numbers that do not match the catalog, the chat flow can offer to research official manufacturer PDFs or leave the parts unmatched.
Parsing can detect a catalog component from a part value, but it does not prove that every ambiguous or generic value identifies the intended orderable part. Review the project components after parsing.
Run /upload-schematics from an existing project to add schematic data to that project. If parsed versions already exist, choose one of these update modes:
  • New version starts from the complete set you select.
  • Amend, add files only keeps existing files when a filename collides.
  • Amend, replace by filename replaces colliding files and keeps the rest of the current version.
Amend is unavailable when files recorded by the current version are missing from .embedder/schematics/sources, because an amend would silently drop them from the design.

​
Plan and implement a change

Use Plan mode when the task has architectural choices, unclear hardware constraints, or changes across several files.
1

Enter Plan mode

Select Plan, press Shift+Tab until Plan is active, or run:
2

Research the current design

Ask for the code path, configuration, tests, and hardware documentation that constrain the change.
3

Write and review the plan

Embedder normally writes the session plan under .embedder/plans and submits it to the plan review view. On a protected or non-writable project root, it uses its per-project application storage instead. Plan mode can edit that plan file, but it cannot modify implementation files.Review the affected files, ordering, failure handling, and verification steps. Edit the plan directly or tell Embedder what to change.
4

Approve and execute

Approving the plan starts a new turn in Act mode. Embedder receives the approved plan and can edit files and run its verification steps.If you reject the plan or send different instructions, implementation does not start.
For a small, fully specified fix, start in Act mode:

​
Add a Mermaid diagram to a plan

The plan view renders fenced Mermaid blocks. Use a diagram only when it makes control flow, state, or component relationships easier to review.
Quote flowchart node labels that contain |, (, ), [, ], {, or }: Use --> or --- in flowcharts. Use ->> or -->> in sequence diagrams. Close every subgraph with end on its own line. Embedder reports Mermaid diagnostics when it writes Markdown and when it submits a plan, but plan submission is not blocked by a bad diagram.

​
Build and test firmware

Build and test commands are project-specific. Record the exact commands in EMBEDDER.md, then ask Embedder to use them rather than infer a generic command.
Use this order:
  1. Run the smallest test that covers the changed code.
  2. Run the required broader host or integration tests.
  3. Build the intended firmware configuration.
  4. Confirm the expected artifact exists and is current.
Do not continue to flashing after a failed build. Diagnose the first useful failure instead of suppressing it or switching toolchains without approval.

​
Build, flash, and observe

Treat each stage as separate evidence.
1

Build the intended image

Ask Embedder to run the recorded build command and identify the exact ELF, HEX, or BIN artifact.
2

Confirm the target

Check the connected board, probe or bridge, power state, and serial transport. If more than one target is present, require an explicit choice.
3

Flash with early output capture

Ask Embedder to flash the artifact and monitor a known port. Capture starts before the flasher runs, so early boot output is preserved. Monitoring stops when the requested string appears, or when the monitor timeout elapses.
Flashing requires a hardware approval unless your current approval mode skips it.
4

Observe the running firmware

Use a live serial monitor when you need to wait for output. Use serial history when the output may already be buffered.
The flash result proves programming only when the flasher reports its verification step. Runtime output proves boot behavior only when it comes from the intended target after that flash.

​
Choose how to observe output

  • Serial history returns buffered UART or RTT output immediately, including output retained after a disconnect. Ask for only new lines when you are polling.
  • Live serial monitor waits for new output, can stop on a string, and can reset the target before capture.
  • Flash with capture programs the target and can capture UART or RTT output from the reset that follows programming.
  • The Monitor Serial tab is useful for manual inspection and sending commands, but an open tab is not evidence that Embedder read a specific line. Ask it to quote the observed output.

​
Debug a hardware failure

Use Debug mode for a defect that needs live device state, GDB, serial, trace, logic, or power measurements. Debug mode appears only in environments that support it.
When a debug session begins, Embedder includes the current hardware picture: detected providers, connected devices, dependencies, helper documentation, and applicable hardware skills. Follow one hypothesis at a time:
1

Observe

Read the failure path, buffered serial output, and current debugger state. Recheck connected hardware if the target, probe, or bridge changed.
2

Hypothesize

State each candidate cause and the observation that would confirm or reject it.
3

Probe

Use the least invasive experiment that separates the leading hypotheses. Prefer paused-state inspection for register, memory, stack, or thread data. Use a hardware script when the experiment must coordinate GDB, serial, RTT, or instruments.
4

Verify

Reproduce the original condition after the fix. Record the observed evidence, not only the absence of a debugger error.

​
Send another prompt while Embedder runs

Submitting during an active turn or compression adds the prompt to that conversation’s queue. The queue runs first-in, first-out and holds up to 10 prompts. Use the queue panel to:
  • select a text prompt and edit it;
  • remove a prompt;
  • choose Send now to move it to the front.
Send now does not interrupt the active turn. Pressing Stop also leaves the queue intact. Remove obsolete follow-ups before stopping if you do not want them to run afterward.

​
Use terminal-only input modes

When you launch the interactive terminal UI with embedder, the ! and ~ prefixes switch the composer into direct input modes. They are not agent modes and are not VS Code shortcuts.

​
Run a shell command yourself

Type !, then enter the command.
The command runs directly in the workspace shell without model interpretation. Because this is a user-issued command, it does not use Embedder’s approval flow. Use the normal prompt when you want Embedder to inspect the result, choose the command, or recover from an error.

​
Send data to the active serial tab

Type ~, then enter the text.
Direct serial send requires an active connection in the terminal serial sidebar. It writes the text to that connection; it does not ask Embedder to interpret the response. Press Escape, or backspace from an empty direct-input field, to return to the normal prompt. See Use Embedder from the CLI for the terminal workflow.
Last modified on August 26, 2026