Helpers
How the agent hands side tasks to helper threads, how they show up in your chat, and how to talk to them.
The agent can hand a self-contained piece of work to a helper: a reviewer, a component researcher, a BOM and sourcing assistant, or a general-purpose copy of itself. Each helper runs in its own thread with its own context, does the task, and hands back a report. Your main thread stays short, and several helpers can work at the same time.
Helpers are available in the desktop app.
Kinds of helper
| Helper | What it does |
|---|---|
| Reviewer | Independent review of a design or a change: Zener source, schematic, board, ERC/DRC/DFM results, manufacturing and sourcing state, checked against your spec and request. Returns findings ranked by severity with evidence |
| Component research | Finds and compares candidate parts for a function using the component library, datasheets and the web. Returns a recommendation with key specs, package, pinout concerns and availability. One per part family; several can run in parallel |
| Sourcing & BOM | Builds or updates the bill of materials, sets each part's manufacturer and MPN in the Zener source, and checks stock, price breaks, MOQ, lifecycle and alternates for your quantity. Flags single-source, low-stock and end-of-life parts |
| General-purpose | A copy of the main agent for any side task that would crowd the thread: digging through logs, surveying a codebase, trying an approach in parallel |
The agent starts helpers when a task benefits from it. You can also ask directly:
Have a reviewer check the power tree and the USB-C input against the spec before I order.
Research three LDO options for 3.3 V at 500 mA from a single Li-ion cell, one helper per family, and compare them.
Update the BOM for 50 units and flag anything with less than 500 in stock.
In the timeline
When the agent starts helpers, a row names them: "Faraday and Hopper started working". Each helper has a name so you can tell several of the same kind apart, and a dotted badge whose pattern shows its kind.
- While a helper works, its badge pulses and its current activity shimmers under the row ("Reading a datasheet…"). With several running, each line starts with the helper's name.
- Hover a name to see the task the agent gave it. Click the name to open its thread.
- When a helper finishes, a collapsed row reads "Faraday finished", "Faraday failed", or "Faraday was stopped". Expand it to read the report. The report ends with Open Faraday thread.
A report is written to stand on its own: the outcome, the findings with evidence (file paths, part numbers, datasheet references, check results), files the helper changed, and open questions for you or the main agent.
Helper threads
Helper threads appear in the Threads sidebar indented under the thread that started them, with the helper's badge instead of a status dot. Hover the badge for its kind and status:
| Status | Meaning |
|---|---|
| queued | Waiting for a free slot |
| working | Running |
| waiting for you | Paused for your answer or approval |
| finished | Handed its report back |
| stopped | Cancelled |
| failed | Ended with an error |
Open a helper's thread to see everything it did: its tool calls, files it read, commands it ran. The first message is a Task from parent thread card with the full brief (and the spec's path, if the parent was implementing one).
You can type in a helper's thread like any other. The helper follows your messages there, which is useful to correct its direction without disturbing the main thread. Approvals and questions from a helper appear in its thread, and the helper shows waiting for you until you answer.
Messages between threads
A helper that is blocked on something only the main agent knows can send it a message, and the main agent can message a running helper. These show as cards:
- Message from helper in the main thread,
- Message from parent thread in the helper's thread.
Click the sender's name on a card to open that thread.
Waiting and background work
The agent either waits for a helper's report or lets it run in the background:
- Waited on: the main run pauses on that step until the report arrives, then continues with it.
- In the background: the main agent carries on (or finishes its turn). The report arrives later as a "finished" row in the main thread, and the main agent picks it up.
If you steer the main thread while it is waiting on a helper, the main agent stops waiting at once; the helper keeps working in the background and sends its report when done.
Limits and behaviour
- Up to 4 helpers run at once per thread; more wait in order (status queued).
- Only top-level threads start helpers. A helper does not start helpers of its own.
- Helpers work on the same project files as the main agent. Edits to the same file by two agents can conflict, so the agent gives overlapping edits to one of them.
- A helper uses the thread's model unless its kind has its own, and always a model your plan includes.
Your own helper kinds
Add a Markdown file per helper to .embedr/agents/ in the project. The front matter describes it; the body is the instructions it follows.
---
name: firmware-reviewer
label: Firmware reviewer
description: Reviews firmware changes for ISR safety, blocking calls in loops, and pin conflicts with the board. Use after firmware edits and before flashing.
effort: high
---
Review only the files the task names. For each finding give the file and line,
why it matters on this MCU, and a concrete fix. Do not edit files.
| Field | Rules |
|---|---|
name |
Lowercase letters, digits and hyphens, up to 40 characters. Defaults to the file name |
label |
Shown in the timeline; up to 60 characters |
description |
Required, up to 600 characters. The agent reads it to decide when to use the helper |
model |
Optional model ID; if your plan does not include it, the thread's model is used |
effort |
Optional: low, medium, high, xhigh or max |
mode |
isolated (default: the helper sees only its brief) or fork (it starts from the current conversation) |
A file is limited to 32 KB and its instructions to 16,000 characters, with up to 24 helper kinds in total. A file named like a built-in helper (reviewer.md, for example) replaces it for that project. A file with an error is skipped and the others still load.