Common Workflows
Step-by-step guides for hardware development, firmware debugging, and everyday tasks with Embedder CLI.
Start a new project
Set up your project
-
Create or select a project
Choose an existing project or create a new one.
-
Select your chip/board
Choose your microcontroller or development board. Embedder loads relevant documentation automatically.
-
Add peripherals
Select peripherals you’re using (I2C sensors, SPI displays, UART modules, etc.). You can also add custom peripherals and upload their datasheets.
-
Generate EMBEDDER.md
Creates an
EMBEDDER.md file with your project context, pin mappings, and configuration. This file is updated throughout your project.
Tips:
- Upload datasheets via the web console (
/console) before starting for best results
- The AI understands your hardware context from the uploaded documentation
- Update
EMBEDDER.md as your project evolves
Hardware interaction
Use the serial monitor
The serial terminal is integrated directly into Embedder. The AI reads serial output automatically.
Open the serial sidebar:
Or use the keyboard shortcut: `Ctrl+“ (backtick)
Auto-connect behavior:
- By default, Embedder auto-connects to your device after flashing
- To disable auto-connect, update your
EMBEDDER.md or prompt:
> don't auto-connect to serial after flashing
Add or modify peripherals at any time:
Example prompts:
> add an SSD1306 OLED display on I2C
> configure UART2 for GPS module at 9600 baud
> what pins should I use for SPI on this board?
Firmware development
Write peripheral drivers
Embedder has context from your datasheets and documentation.
> write an I2C driver for the BME280 sensor
> create a UART driver for the ESP32
> implement SPI communication for the SD card module
Build and flash
Embedder knows the required toolchains and dependencies from the project catalogue. Ask for help getting started:
> help me install the dependencies for this project
> flash the firmware to the device
> build and flash, then show me the serial output
Work with HALs and SDKs
Embedder understands vendor-specific HALs and SDKs:
> how do I configure the STM32 HAL for I2C?
> show me how to use the ESP-IDF GPIO driver
> what's the correct way to initialize DMA on this chip?
Debug with serial output
The AI reads serial output directly and can analyze issues in real-time.
Analyze errors
> what's causing this error in the serial output?
> the device keeps resetting, analyze the crash dump
> parse the debug logs and find the issue
Share screenshots
Drag and drop images or paste with Ctrl+V:
> here's a screenshot of the error, what's wrong?
> this is the oscilloscope output, is the signal correct?
Trace execution
> add debug prints to trace the initialization sequence
> why isn't the interrupt handler being called?
Plan mode vs Act mode
Embedder has two modes for different workflows.
Act mode (default)
Full tool access. Embedder can read, write, and execute.
Use for:
- Writing and modifying code
- Building and flashing firmware
- Making changes to your project
Plan mode
Read-only analysis. Embedder researches without making changes.
Use for:
- Exploring unfamiliar code
- Planning complex refactors
- Reviewing architecture before changes
- Analyzing datasheets
Toggle between modes:
- Keyboard:
Shift+Tab
- Commands:
/plan or /act
Start in plan mode:
> /plan
> analyze the power management implementation and suggest improvements
Documentation and context
Leverage uploaded documentation
Upload datasheets and manuals via the web console (/console). Embedder uses them automatically:
> what's the maximum I2C clock speed for this sensor?
> show me the register map for the accelerometer
> what are the power consumption specs in sleep mode?
Hardware-aware assistance
Embedder understands your specific hardware:
> which pins support PWM on this board?
> what's the pin mapping for the Arduino header?
> can I use DMA with this UART peripheral?
Bash mode
Bypass the AI agent and execute terminal commands directly using the ! prefix.
This runs the command in your terminal without AI interpretation. Useful for quick commands when you don’t need AI assistance.
Serial send mode
Send messages directly to your MCU over serial using the ~ prefix.
This sends the text directly to your device’s serial console. Useful for:
- Sending AT commands
- Interacting with device CLI/REPL
- Manual debugging commands
Reference files and directories
Use @ to quickly include files or directories in your prompts.
Reference a file
> explain the logic in @src/main.c
> what does @drivers/i2c.h do?
Reference a directory
> what's in @src/drivers/?
> show me the structure of @lib/
Multiple references
> compare @src/old_driver.c and @src/new_driver.c
Session management
Switch teams and projects
/team # Switch team (if you have multiple)
/project # Switch to a different project
Resume previous sessions
/history # Browse and resume past conversations
Manage context
For long conversations:
/compress # Compress conversation to save context
Track tasks
View your current task list:
Quick reference
| Workflow | Command/Shortcut |
|---|
| New project setup | /project → /chip → /peripheral → /init |
| Serial monitor | /serial or `Ctrl+“ |
| Switch mode | Shift+Tab or /plan /act |
| Switch model | /model or Ctrl+Alt+B |
| Add peripheral | /peripheral |
| Reference file | @filename in prompt |
| Bash mode | !command (e.g., !ls) |
| Serial send | ~message (e.g., ~help) |
| Undo last message | /undo or Ctrl+Z |
| Rewind conversation | /rewind or Ctrl+Z (2x) |
| Resume session | /history |
| Compress context | /compress |
| View tasks | /tasks |
| Web console | /console |
| Get help | /help |
Tips for best results
- Upload documentation first - Add datasheets via the web console (
/console) before starting
- Use /init early - Generate
EMBEDDER.md to give the AI full project context
- Be specific about hardware - Mention exact part numbers and pin configurations
- Use plan mode for research - Explore codebases without accidental changes
- Keep EMBEDDER.md updated - Add notes about your project as it evolves
Last modified on March 5, 2026
