Embedr Agent
Chat threads, the composer and attachments, approvals, the activity timeline, steering, checkpoints, notifications and Voice Mode.
Embedr Agent works inside your project: it reads and edits files, builds and flashes firmware, works on Zener sources, schematics and boards, reads datasheets and drives the mechanical workspace. You talk to it in the chat panel of a project.
Where the chat lives
The title bar has a layout switch:
| Layout | What you see |
|---|---|
| Agent layout (Chat in center) | A Threads sidebar on the left, the chat in the middle |
| IDE layout (Editor in center) | The editor in the middle, the chat in a side panel with New chat and a history button in its header |
On an empty chat Embedr offers three starters: Review project, Find risks and gaps and Suggest next steps.
Chat threads
Each project has its own threads. Keep one thread per task ("bring up the BME280", "fix upload on the S3 board", "route the power section").
| Action | How |
|---|---|
| Start a thread | New chat in the Threads sidebar or the chat header |
| Switch threads | Click a thread in the sidebar, or the history button in the chat header |
| Rename | Double-click the title (sidebar row or chat header), type, press Enter. Esc cancels |
| Find a thread | Search icon in the Threads header, then Filter threads... |
| Delete | Hover a thread and click the trash icon |
| Copy the chat file's path | Hover a thread and click the copy icon |
Embedr names a new thread from your first message and replaces the placeholder name with a generated one shortly after. A name you type yourself always wins.
The sidebar shows the newest 15 threads; click N more for the rest. Row markers:
- a moving dotted loader: Agent is working...
- a green dot: Agent finished since you last looked
- a small number: messages waiting in that thread's queue
- an indented row with a dotted badge: a helper thread under the thread that started it
In the desktop app, chats are stored outside the project folder, under ~/EmbedrProjects/.embedr/<project-name>/chats/, so they are not committed with your code. In the browser they are stored with the web project.
The composer
The composer placeholder reads "Ask about your project… @ files · paste images".
| Key | Action |
|---|---|
| Enter | Send (or queue, while the agent is working) |
| Shift+Enter | New line |
| Shift+Tab | Turn Plan Mode on or off |
| Esc | Closes the @ list or a menu. It never clears your draft |
A draft stays with its thread when you switch away and back.
Mention files and datasheets
Type @ to open a list of project files and indexed datasheets. Keep typing to filter (up to 20 matches), use the arrow keys, and press Enter or Tab to pick one. The file is attached as a chip and @name stays in your text.
Attachments
Attach with the paperclip, by dropping files on the chat, or by pasting. Click any tile to preview it; the preview has a remove button.
| What you attach | What happens |
|---|---|
| Images (PNG, JPEG, WebP, GIF) | Sent as images. Large images are scaled to 2048 px on the long edge |
| BMP, SVG pasted as an image, AVIF, ICO, APNG | Converted to PNG or JPEG first |
| HEIC, HEIF, TIFF | Refused: "HEIC images aren't supported. Export as PNG or JPEG and attach again." |
Source code, KiCad files (.kicad_sch, .kicad_pcb, .kicad_sym, .kicad_mod…), Zener .zen, Gerbers and drill files, SPICE netlists, Markdown, JSON, YAML, CSV, logs, Intel HEX, STEP |
Read as text and included in the message |
| Unknown file types | Accepted if the content looks like text |
Altium .SchDoc, .PcbDoc, .PrjPcb, .OutJob, .SchLib, .PcbLib, .IntLib |
Turned into a text summary: components, nets, layer stack and rules |
| Processed as a datasheet and attached as one. Only inside a project | |
Archives, executables, firmware binaries (.bin, .elf, .uf2), STL, 3MF, GLB, Office documents, media, fonts |
Refused: ".zip is a binary format, so its contents can't be read as text." |
Limits per message:
| Limit | Value |
|---|---|
| Attachments | 24 (extra files are skipped with "Too many attachments") |
| Images | 8 |
| All images together | about 18 MB after conversion |
| Single image before conversion | 40 MB |
| Text read from one file | 256 KB; longer files are cut and the agent is told to read the rest from the project |
| Altium file | 80 MB |
Pasting 2,500 characters or 40 lines or more creates a Pasted text attachment instead of filling the box. Open it and click Insert as text if you want it inline.
The ring at the right of the composer shows how much of the model's context the thread uses, for example "120K of 272K tokens · 56% left". If a long draft will not fit, the tooltip says so; remove attachments or start a new chat.
Send selections and output to chat
Select text and click the floating Add to Chat button in:
- the code editor,
- a terminal tab,
- the build Output panel,
- the Serial Monitor.
When a build fails, the Output panel shows Ask agent to fix. Board, schematic and 3D views have Add to chat for selected components (press A on a selected 3D component). The mechanical workspace adds part notes as chips; see Mechanical design.
Agent preferences
The sliders button next to the model picker opens the preferences menu. Each change is announced to the agent in the thread.
| Section | Option | Effect |
|---|---|---|
| Agent behavior | Auto-flash | After a successful build, flash the selected device; asks you to pick a port if none is safe |
| Auto-debug | When build, flash, runtime or serial output shows a problem, inspect it, fix, and re-run checks | |
| Auto-review | Before finishing code or hardware changes, review the changes and call out remaining risks | |
| Interface | Follow agent | Switch tabs and panels to what the agent is doing (for example the Output after a compile) |
| Terminal approvals (desktop) | Default permissions, Low-risk auto approve, Full access | How terminal commands are approved; see below |
When Full access is on, the button shows a warning shield and the label "Full access".
Approvals
Some actions stop and ask you in the composer area before they run.
| Asks for approval | Notes |
|---|---|
| Terminal commands (desktop) | Depends on the Terminal approvals mode and Settings → Command Approval |
| The agent typing into one of your terminal sessions | Always asks |
| PCB Auto Place and PCB Auto Layout | Always asks; needs a paid plan, otherwise the card offers View plans |
| Exporting PCB artifacts (desktop) | Always asks |
The card shows the command or action, the risk reasons (when Show Risk Analysis is on) and these choices:
| Choice | Meaning |
|---|---|
| Allow once | Run it now |
| Always allow | Run it now and auto-approve this category from now on. Not offered for destructive commands |
| Enable full access | Run it and stop asking for any terminal command |
| Decline | Do not run it; the agent is told |
Click Confirm to answer. Terminal modes:
- Default permissions: read-only, build and version-control commands run without asking; everything else asks.
- Low-risk auto approve: also runs commands that do not modify or delete files.
- Full access: no terminal prompts. The same as YOLO Mode in Settings.
If an approval comes from a thread or project you are not looking at, a popup appears; minimize it to a pill in the title bar. In the browser, commands run in a cloud sandbox without prompts ("Cloud sandbox: commands run without approval prompts."); PCB automation still asks.
The activity timeline
The agent's tool calls are grouped between its messages. Each group is collapsed and summarized, for example "Read 3 files, ran 10 commands". Expand a group to see each call; expand a call for its details (the full command, diffs, output). Images produced by the tools show as thumbnails at the right of the group and open in a preview.
While a run is active, the latest group shimmers with the current activity ("Searching project files…", "Thinking…", "Compacting context…", "Waiting for you"). The run's duration appears once, at the end:
- Worked for 4m 12s under the final reply,
- Working for… while it runs,
- Failed after… or Cancelled after… when it ends early.
Time spent waiting for your answers or approvals is not counted.
When a long thread nears the context limit, Embedr summarizes earlier turns automatically. A divider marks it: "Compacting context..." then "Context automatically compacted".
Reply rows also have copy, Helpful? thumbs (sends feedback on that reply), and reasoning summaries where the model provides them.
While the agent is working
You can keep typing. The send button becomes Queue message, and queued messages stack above the composer.
| Control | Effect |
|---|---|
| Steer | Desktop: the message joins the running run before its next step; the row shows Joins next step. Browser: the current run stops and your message is sent next |
| Remove (x) | Drop the queued message |
| Send next | Shown when nothing is running; sends the first queued message |
| Square stop button | Cancel Generation |
Queued messages are sent in order when a run finishes normally. After a cancel or an error they wait for Send next.
If a run stops with Agent Paused, click Continue to let it keep going.
Questions from the agent
When the agent needs a decision only you can make, it asks one to four questions in the composer area instead of guessing. Pick an option, choose Something else and type, or choose You decide to let it pick a default and record it as an assumption. See Plan Mode for the full flow.
Checkpoints and undo
With Enable Chat Checkpoints on (Settings → General), Embedr snapshots the project before each message you send.
- Restore checkpoint and edit message (on your earlier messages): reverts project files to that point, removes everything after it, and puts the message back in the composer to edit.
- Delete from here (on messages without a checkpoint): removes the message and everything after it from the conversation. Files are not touched.
Both ask for confirmation. In the mechanical workspace, Cmd+Z can also take back the agent's last turn; see Mechanical design.
Notifications
Embedr notifies you when a run finishes, fails, or needs an answer or approval, if Embedr is in the background or you are looking at another thread. The first time you hand work to the agent from the Home screen or click Implement this spec, a Know when it's done prompt above the composer offers Turn on. On macOS, if no notification appears, allow Embedr in System Settings → Notifications. In the browser you can also choose email.
The bell in the title bar lists recent notifications; click one to open its thread. Change what notifies you in Settings → Notifications.
Voice Mode
Voice Mode is in the desktop app on Hobby and Pro. Click the microphone in the composer (Start voice mode). Talk normally; the orb shows the state: Listening, Thinking…, Working with Embedr Agent…, Speaking, or Approval needed in Embedr. Voice replies appear in the thread marked Embedr Voice.
- Click the orb while it speaks to stop the reply.
- The left button mutes the microphone; the x closes voice mode.
- Minimize the main window and a floating orb stays on top; click it to return to Embedr.
When something goes wrong
| Message | What to do |
|---|---|
| Reconnect ChatGPT | Reconnect your ChatGPT account in Settings → AI Accounts, then retry |
| OpenCode balance required | Add balance to your OpenCode account or pick another model |
| Model Usage Limit / Provider Rate Limit | Wait for the reset, add usage, or switch models; see Models |
| "This conversation has become too long. Please start a new chat." | Start a new thread and reference the files or spec you need |
| Reauthenticate to continue | Sign in again |
Prompt examples
Name the outcome, the limits, and the check.
Firmware:
This ESP32-S3 project should read the BME280 over I2C every 2 s and print temperature, humidity and pressure at 115200 baud. Inspect the current code, install the library if it is missing, build, and leave the Wi-Fi code alone.
@main.cpp The device resets when the motor starts. Read the serial log I added and tell me whether this is a brownout or a watchdog reset before changing anything.
Hardware:
Add a USB-C input with a 3.3 V LDO to the board. Use the AP2112K datasheet I imported for the capacitor values, keep the existing I2C pinout, then build the Zener source and show me the ERC result.
Route the current board, then list any unrouted nets and the DRC errors that remain.
Mechanical:
Design a snap-fit enclosure for this board with a 2 mm wall, an opening for the USB-C connector, and four M2.5 standoffs at the mounting holes. Show me a section view when it builds.