Get reliable results

A reliable request says what should change, what must stay the same, and how to check the result. Use the habits on this page when a task touches hardware, spans several files, or needs proof that it worked.

Give the task a finish line

State the change, the constraints, and the checks that prove it is done:

Update @drivers/bme280.c to handle a short I2C read. Keep the public API and
retry count unchanged. Add a two-byte-response test, run the driver tests,
and build the firmware. Report the observed results.

For a bug, include the symptom, the conditions that trigger it, and the expected behavior. For research, ask for findings before Embedder picks an implementation.

Attach precise context

Type @ to attach a file or folder. Point to the smallest file or folder that covers the task:

You attach	Embedder receives
A text file	Its first 500 lines.
A folder	A listing of its entries, not the files inside.
A PDF	Its first 15 pages. See Work with a long PDF.
A binary file, or a text file over 1 MB	Only its name. Ask Embedder to read the part you need.

If the project has uploaded schematics, refer to a component or net. Type @ and choose it from the list, or write the reference yourself:

Trace @sch:net:I2C1_SDA from @sch:component:U3 to the MCU and compare it
with @src/board/pins.c.

Paste or drop an image into the chat when its visual detail matters. Say what to look at, such as the failing transaction in a logic capture. To use a datasheet or reference page from the web, give Embedder the URL. Embedder fetches web pages and PDFs from your computer, so your network’s access rules apply; it doesn’t fetch local or private network addresses. Downloaded files are cached in ~/.embedder/downloads/. To keep a copy in the project, ask Embedder to save it to a folder, such as docs/. Saving into the project asks for edit approval and isn’t available in Plan mode.

Work with a long PDF

Embedder reads a PDF up to 15 pages at a time. To read further, ask for a specific range, such as pages 1200–1214, or a single page to zoom in. For a document you’ll come back to, have Embedder index it. An indexed PDF is searchable in later sessions on the project, so Embedder doesn’t page through it again.

For a PDF over 30 pages, Embedder suggests indexing it, unless the project already has it.
A PDF over 50 MB is too large to read page by page. Embedder offers to index it instead.
Indexing uploads the PDF to the project. Embedder always asks for your approval first, and it can’t index in Plan mode, so switch to Act mode.

Keep project instructions current

Run /init to check the project’s build, test, debug, and deployment setup. Embedder asks you to confirm what it found, then creates or refreshes EMBEDDER.md. Record exact commands, how to select the target, the expected output, and which code is generated and should not be edited. Run /init again when the toolchain, board, or build configuration changes. Recheck commands that worked on a previous workstation.

Pick the right mode

Mode	Use it to
Plan	Compare approaches and review a plan before Embedder edits implementation files.
Act	Implement, build, run tests, flash, and run ordinary hardware checks.
Debug	Do everything Act does, plus managed GDB setup and target-state inspection for faults and hangs.

Approval settings are separate from the mode. See Agent modes for details.

Ask for evidence at each stage

Break hardware work into checks, and say when to stop:

Run the parser tests. If they pass, build the selected target and identify the
artifact. Flash only the intended board, then wait up to 15 seconds for the
self-test result. Stop if the target is ambiguous or a required check fails.

Ask for evidence that answers the actual question: a passing regression test, a verified image, a specific log line, a decoded frame, or a measured waveform.

Preserve useful hardware state

A reset or reflash can destroy evidence. If the board is faulted, ask Embedder to attach without programming or resetting it before anything changes. For measurements, name the instrument, the wiring, the limits, and the duration. When you compare before and after, keep the same firmware and workload. Note any halt or instrumentation that could change timing.

Steer work in progress

Send a message while Embedder is working to add a constraint or correct course. Embedder picks it up at its next step. Remove queued messages that no longer apply. See Send prompts during a turn.

Reuse what worked

Save	As
A repeatable bench check	A hardware script
A procedure your team repeats	A skill
A confirmed project fact or decision	Project memory
A task that should keep going until a check passes	A goal

Before you treat a task as complete, review the final diff and any limitations Embedder reports.

Get started

Set up a project

Work with Embedder

Workflow guides

Monitor and debug

Code analysis

Automation

Settings and help

Reference