Getting Started

Quickstart

Flash is a terminal-native AI assistant for embedded firmware and hardware engineering. This guide takes you from a fresh install to your first hardware-aware change — on a local or cloud model — in a few minutes.

Before you begin

You'll want a few things ready:

• A terminal. Any modern one works; Flash runs a full-screen interface inside it.
• A firmware project — a folder with a platformio.ini, sdkconfig, west.yml, an .inosketch, or similar. No project yet? Flash's launcher can scaffold one for you.
• Either a local model server (Ollama, LM Studio, llama.cpp, MLX) ora cloud API key. You'll wire one up in Step 2.

Step 1: Install and launch Flash

Install the Flash CLI, which ships the full-screen terminal app:

# Installs uv if needed, then the flash CLIcurl -fsSL https://flashagent.dev/install.sh | sh

Then launch Flash from your project directory:

cd your-projectflash

Step 2: Set up an AI provider

Flash runs on local or cloud models. The first time you start, point it at one with flash setup, which detects what you have and writes your config:

flash setup                              # auto-detect a local server or a cloud keyflash setup --local                      # force local (Ollama / MLX / llama.cpp / LM Studio)flash setup --cloud --provider openrouterflash doctor                             # verify: providers up, models, keys set

Prefer to sign in for hosted usage? flash login connects your Flash account or GitHub Copilot.

Step 3: Start your first session

On startup, Flash either opens straight into your project or shows a launcher. From there you'll confirm the board and its components, then analyse everything.

Open or create a project

Run flash inside a firmware folder and it opens directly. Run it anywhere else and the project launcher appears — search your recent projects, or choose ＋ Create new project to pick a microcontroller/board, a framework, and a build system (PlatformIO, or a native ESP-IDF / Zephyr / Arduino / Pico toolchain).

Confirm your board

Flash grounds its answers and generated code in the platform that matches your board — SDK constraints, register maps, and peripheral details included. The PROJECT panel shows what it detected.

Add your peripherals

Tell Flash which parts are on the board so it can pull the right datasheets. Open the picker with /peripherals and search the built-in ~5,000-part database, or add MPNs directly:

/peripherals add BME280 W5500 STM32F407VGT6/peripherals resolve       # fetch metadata + datasheets

Analyse the project

Finally, run /init. This runs a deterministic four-stage pipeline — no LLM — that reads your firmware and writes a structured model of the board, code, and architecture to a .flash/ directory, plus a FLASH.md the agent uses as project context. This is what makes Flash board-aware.

/init

Step 4: Ask your first question

With the project analysed, ask hardware- and code-specific questions in natural language. Flash pulls from the board model, your datasheets, and your files automatically:

what peripherals are connected on this board?which pins are assigned to SPI1, and at what clock?what does main.c do, and where is the entry point?

Step 5: Make your first code change

Now try a concrete task:

add a function to toggle the LED on GPIO 13

Flash will:

1. Find the right file using the project index.
2. Read the relevant pin and register definitions from the board model.
3. Show a diff and explain its reasoning.
4. Ask for your approval before writing.

Step 6: Build, flash & watch serial

Open the BUILD panel to install the toolchain, build, and flash, then watch output live in the DEBUG panel — a multi-tab serial monitor with log-level colouring. Flash resolves the right build and flash commands for your board automatically.

More in Common Workflows.

Step 7: Fix a bug or add a feature

Describe a symptom and let the debug agent work the fix loop against your board — plan → fix → build → flash → verify:

my SPI peripheral isn't responding — help me debug

Give it a success criterion (a serial marker that should appear or stop) and it verifies the fix on-target instead of guessing. Flash checks your code against the board model for the usual culprits — wrong SPI mode, invalid alternate function, missing pull-up, clock mismatch — and proposes a fix you can approve, flash, and re-test.

Step 8: Try other common workflows

A few more things to point Flash at:

• Write a driver. write an I2C driver for the temperature sensor
• Configure a peripheral. set up PWM on Timer 2 at 1 kHz
• Generate init code. initialize the ADC for 12-bit resolution on channel 5
• Get an architecture report. /architecture runs a deterministic, cited report over the whole project.

See Common workflows for the full set.

Pro tips for beginners

• Run /init first. Every answer is sharper once the board model and FLASH.md exist.
• Be specific.Instead of "configure the timer", try "configure Timer 3 for a 10 ms interrupt using the 16 MHz HSI clock".
• Break big tasks into steps. Number them and Flash works through them in order.
• Explore in plan mode. /mode plan has Flash investigate and propose before it edits.

What's next

Getting help

Type /help inside Flash, run flash doctor to diagnose provider issues, or write to contact@flashagent.dev. During the private beta we'll happily walk through your first session with you.