Best Practices

This page covers proven patterns for getting the best results from Embedder, gathered from engineers using it across a wide range of environments. The most important factor is session length. As a session grows longer, Embedder accumulates conversation history, file contents, and command outputs. When there’s too much accumulated context, Embedder may lose track of earlier instructions, make more errors, or behave inconsistently. Keeping sessions focused is the single most effective way to maintain accuracy. Use this guide as a starting point. Pay attention to what works and what doesn’t.

Help Embedder verify its work

Include tests or expected outputs so Embedder can check itself.

Embedder performs best when it can verify its own work. Without clear success criteria, it may generate solutions that appear correct but fail in practice. In those cases, you become the only source of feedback, and every mistake requires manual review and intervention.

Strategy	Before	After
Provide verification criteria	”implement a function that reads a temperature sensor"	"implement read_temperature(). When the sensor returns raw value 0x0190, the function should return 25.0°C. Include unit tests with mocked I²C reads and verify outputs for [0x0000 -> 0.0°C, 0x0190 -> 25.0°C, 0x0320 -> 50.0°C]. Tests must pass.”
Address root causes, not symptoms	”the build is failing"	"the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error”

Your verification can take many forms, such as a test suite, a linter, or a Bash command that validates output. Invest the time to make these checks reliable and thorough, since strong verification enables consistent, dependable results.

Explore and plan, then code

Separate research and planning from implementation to improve results.

Letting Embedder jump straight to coding can produce code that solves the wrong problem. Use Plan Mode to separate research and planning from execution. The recommended workflow has four phases:

Explore

Enter Plan Mode. Embedder reads files and answers questions without making changes.

Embedder (Plan Mode)

Read /firmware/src and explain how GPIO, UART, and the main loop are initialized. 
Also check how the board clock and pin configuration are set up.

Plan

Ask Embedder to create a detailed implementation plan.

Embedder (Plan Mode)

I want to add a feature that blinks an LED at 1 Hz and prints "alive" over UART every second.
What files need to change? How should the timer interrupt be configured?
Create a step-by-step implementation plan and list tests to verify it works on hardware.

When Embedder is done creating a plan, you can either approve it and continue with execution or give it feedback on what to change. You can manually edit the plan by going to .embedder/plans in your projects directory.

Implement

Switch back to Act Mode and let Embedder code, verifying against its plan.

Embedder (Act Mode)

Implement the LED blink + UART heartbeat from your plan. 
Configure a hardware timer interrupt.
Add a small test or debug log to confirm the ISR fires every 1 second.
Build the firmware and fix any compile errors.

Commit

Ask Embedder to commit with a descriptive message and create a PR.

Embedder (Act Mode)

Commit with a descriptive message and open a PR.

Plan Mode can improve outcomes, but it is not always necessary and can slow down simple work. When the task is straightforward and limited in scope, such as correcting a small bug, adding a debug statement, or making a minor rename, it is usually faster to execute the change immediately. A dedicated planning step is most effective for more complex situations, especially when the solution is unclear, the update touches several parts of the codebase, or you are working with unfamiliar code.

Provide specific context in prompts

The more precise your instructions, the fewer corrections you’ll need.

Embedder can often infer your intent, but it does not have implicit knowledge of your goals or assumptions. Be explicit and precise in your instructions. Reference the exact files to modify, state any constraints or requirements, and link to relevant examples or patterns to follow.

Strategy	Before	After
Scope the task. Specify which file, what scenario, and testing preferences.	”Add tests for uart.c"	"Write a hardware-level test for drivers/uart.c that verifies RX buffer overflow handling. Simulate 256+ bytes arriving back-to-back and assert no memory corruption. Avoid mocks; use existing HAL test harness.”
Point to sources. Direct Embedder to the source that can answer a question.	”Why is the SPI driver so complicated?"	"Read drivers/spi.c and its git history and summarize how the SPI driver has evolved. Explain any hardware constraints that influenced the design.”
Reference existing patterns. Point Embedder to patterns in your codebase.	”Add an I2C sensor driver"	"Look at how drivers/adc.c and drivers/uart.c structure init/config/read functions. Follow the same pattern to implement drivers/i2c_temp_sensor.c. Match naming, error handling, and ISR style. Don’t introduce new frameworks.”
Describe the symptom. Provide the symptom, the likely location, and what “fixed” looks like.	”Fix the LED bug"	"The status LED randomly stops blinking after ~10 minutes. Likely related to the timer ISR in src/timer.c. Reproduce with a long-running loop, add logging to confirm missed interrupts, then fix so the LED maintains a stable 1 Hz blink for 30+ minutes.”

Vague prompts can actually be quite useful when you are exploring or are open to suggestions. Asking “What bugs are in this file?” may surface things you wouldn’t have otherwise found.

Providing context

You can provide rich data to Embedder in several ways:

Reference files with @ instead of describing where code lives.
Reference documentation in your project workspace.
Give URLs for documentation and online references.

Setup your environment

A small amount of upfront setup can make Embedder far more effective in every session. Taking the time to configure your environment and provide the right context helps the agent work more accurately, consistently, and efficiently from the start.

Writing an `EMBEDDER.md` file

Run /init to generate a starter EMBEDDER.md file based on your current project structure.

Embedder automatically reads an EMBEDDER.md file at the beginning of every session. Use this file to define important details such as common bash commands, coding conventions, and workflow guidelines. This provides persistent context that cannot be reliably inferred from the codebase alone. The /init command scans your project to identify build systems, test frameworks, and recurring patterns. This creates a strong starting point that you can then customize and refine. There is no strict structure required for EMBEDDER.md, but it should remain concise and easy to understand. Aim for clear, human readable instructions rather than lengthy documentation.

Embedder.md

# Code style
- Follow the project’s C or C++ style guide and keep functions small and single purpose
- Use consistent naming for peripherals and drivers such as uart_init, spi_write, adc_read
- Avoid dynamic allocation in firmware. Prefer static or stack memory

# Workflow
- Always build the firmware after changes and fix all compiler warnings
- Flash and verify on real hardware or simulation before marking tasks complete
- Run targeted unit tests or hardware specific tests instead of the full suite for faster iteration

EMBEDDER.md is loaded at the start of every session, so only include information that applies broadly across your entire project. Keep the file short and focused. For each line, ask yourself, “If this were missing, would Embedder make mistakes?” If the answer is no, remove it. An oversized or cluttered EMBEDDER.md dilutes the important guidance and makes it more likely that Embedder overlooks your actual instructions.

Include	Exclude
Commands Embedder can’t guess	Anything Embedder can see in code or docs
Unique code style rules	Standard language conventions
Testing instructions and preferred test runners	Detailed API documentation (link to docs instead)
Repository etiquette	Information that changes frequently
Developer environment quirks (required env vars)	File-by-file descriptions of the codebase
Common gotchas or non-obvious behaviors	Self-evident practices like “write clean code”

If Embedder keeps doing something you’ve explicitly prohibited, your EMBEDDER.md is probably too long and the rule is getting buried. If it asks questions that are already answered in the file, the phrasing is likely ambiguous or unclear. Treat EMBEDDER.md like code: review it when behavior goes wrong, regularly prune unnecessary or redundant lines, and test changes to confirm that Embedder’s behavior actually shifts. You can also improve adherence by adding clear emphasis such as “IMPORTANT” or “YOU MUST.” Check the file into git so your team can contribute, since small improvements compound over time and make the document increasingly valuable.

Provide documentation

Run /peripheral to change what peripheral documentation is associated with your project

Many platforms and peripherals have pre-indexed documentation. If you find Embedder is getting things wrong about your board or peripherals, consider uploading supplemental documentation via the web console. If you’ve added your own platform or peripheral, be sure to upload sufficient and up to date documentation. You can add more documentation for your platform or peripherals by using the /console command and uploading more documentation in the projects section of the web app. The /console command lets you upload additional documentation to existing platforms and peripherals in your project.

Use CLI tools

Tell Embedder to use tools like gh, west, or openocd when interacting with external services.

The most efficient way to interact with external services is through CLI tools. If you use GitHub, install the gh CLI. Embedder knows how to use it for creating issues, opening pull requests, and reading comments. Without gh, Embedder can still use the GitHub API, but unauthenticated requests often hit rate limits. Embedder is also great at learning CLI tools it doesn’t already know. Try prompts like Use 'cli-tool --help' to learn about more about the cli tool, then use it to solve A, B, C.

Ask questions about your codebase

Ask Embedder questions you’d ask a staff or senior engineer.

When onboarding to a new codebase, use Embedder for learning and exploration. You can ask Embedder questions you would ask another engineer:

How does error logging work?
How do I read data from the sensor used in this project?
What does handle_sample() do on line 134 of foo.c?
What edge cases does TIMER_CTRL handle?
Why does this code call foo1() instead of foo2() on line 173?

This can significantly speed up onboarding and reduce the load on other engineers.

Manage your session

Conversations are persistent, and the changes made during them can be reversed.

Course-correct early and often

Correct Embedder early and often.

Embedder performs best with a tight feedback loop. Correcting Embedder quickly produces better solutions at a faster pace.

Esc: Stop Embedder mid-action with the Esc key. Context is preserved, so you can redirect.
Ctrl + z (2x) or /rewind: Press Ctrl + z (2x) or run /rewind to open the rewind menu and restore previous conversation and code state.
Ctrl + z or /undo: Press Ctrl + z or run /undo to have Embedder revert its most recent change.
/clear: Reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.

If you’ve corrected Embedder more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.

Manage context aggressively

Run /clear between unrelated tasks to reset context.

Embedder automatically compresses conversation history during long sessions, preserving important code and decisions while freeing space. During longer sessions, Embedder’s context window can fill with irrelevant information. This reduces performance and sometimes distracts Embedder.

Use /clear frequently between tasks to reset the context window entirely
When auto compression triggers, Embedder summarizes what matters most, including code patterns, file states, and key decisions
For more control, you can run /compress to choose when compression occurs
Customize compression behavior in EMBEDDER.md with instructions like "When compressing, make sure to keep track of the full list of modified files" to make sure any important context survives summarization

Use subagents for investigation

Delegate research with "use subagents to investigate X". They explore in a separate context, keeping your main conversation clean for implementation.

Subagents are one of the most effective tools for keeping sessions focused. When Embedder researches a codebase, it reads many files, which can slow performance in long sessions. Subagents complete the task in a separate context window and report back summaries:

Use subagents to investigate how our firmware initializes the CAN peripheral, handles message TX/RX interrupts, 
and whether we already have reusable CAN drivers I should build on instead of writing new code.

The subagent explores the codebase, reads relevant files, and reports back with findings, all without cluttering your main conversation.

Rewind to previous checkpoints

Every action Embedder makes creates a checkpoint. You can restore the conversation and code to a previous state.

Embedder automatically checkpoints before changes. Run /undo to undo the last change or /rewind to open the checkpoint menu. Instead of carefully planning all your moves, you can tell Embedder to try something and if it doesn’t work, rewind and try it another way.

Checkpoints will only track changes made by Embedder.

Resume conversations

Run /history to pick up a conversation where you left off.

Embedder keeps a copy of conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don’t have to re-explain the context.

Avoid pitfalls

These are some helpful tips to avoid common mistakes.

Run /clear between unrelated tasks. Otherwise, you may bloat your context window with lots of irrelevant information.
Run /clear after failures. If Embedder does something wrong, after two or three failed corrections run /clear and write a better initial prompt incorporating what you learned, as context will be polluted with failed approaches.
Add additional documentation. If Embedder seems to be misunderstanding aspects of your hardware. Consider uploading additional, or replacing current, documentation.
Prune EMBEDDER.md often. If EMBEDDER.md is too long, Embedder will ignore much of it as the important rules will get lost in the noise. The less guidelines in EMBEDDER.md the more focused Embedder will be on upholding those guidelines.
Scope tasks and use subagents. If you ask Embedder to “explore” something and don’t scope it down, Embedder can end up filling its context rapidly. Scope tasks or use subagents to preserve context.

Core Concepts

Customizations

Debug Mode

Headless

Integrations

Product Updates

Help Embedder verify its work

Explore and plan, then code

Provide specific context in prompts

Providing context

Setup your environment

Writing an `EMBEDDER.md` file

Provide documentation

Use CLI tools

Ask questions about your codebase

Manage your session

Course-correct early and often

Manage context aggressively

Use subagents for investigation

Rewind to previous checkpoints

Resume conversations

Avoid pitfalls

​Help Embedder verify its work

​Explore and plan, then code

​Provide specific context in prompts

​Providing context

​Setup your environment

​Writing an EMBEDDER.md file

​Provide documentation

​Use CLI tools

​Ask questions about your codebase

​Manage your session

​Course-correct early and often

​Manage context aggressively

​Use subagents for investigation

​Rewind to previous checkpoints

​Resume conversations

​Avoid pitfalls

Help Embedder verify its work

Explore and plan, then code

Provide specific context in prompts

Providing context

Setup your environment

Writing an `EMBEDDER.md` file

Provide documentation

Use CLI tools

Ask questions about your codebase

Manage your session

Course-correct early and often

Manage context aggressively

Use subagents for investigation

Rewind to previous checkpoints

Resume conversations

Avoid pitfalls