EmbeddedPilot

An AI software engineering agent for embedded Linux, STM32 and Yocto development.

一个面向 STM32 / Embedded Linux / Yocto 开发场景的自主软件工程 Agent。

EmbeddedPilot is not a re-skinned chatbot. It is a coding agent that can take a real engineering task and run the full loop:

understand task → inspect project → read source → search code → analyze logs
→ modify code → build → test → analyze failure → repair → verify → produce a git patch

It is built as a package on top of the Pi coding agent and uses Pi's extension API and SDK. It does not fork Pi and does not reimplement what Pi already solves (providers, agent loop, sessions, TUI, basic tools).

Status: Phase 2 (build engineering). See docs/roadmap.md.

What works today

Eighteen agent tools, registered through the Pi extension API:

Tool	Purpose
embedded_project_info	Detect board family, Yocto MACHINE/DISTRO/layers, kernel version, U-Boot / TF-A / OP-TEE trees, device trees, build systems, cross toolchains, git state
embedded_diagnostics	Read-only system inspection from a fixed allowlist: uname, /proc/cpuinfo, free -h, df -h, dmesg, ls /dev, /proc/mounts, /proc/iomem, lshw
git_status / git_diff / git_log / git_branch / git_show	Read-only repository inspection
git_create_patch	Write all current changes (vs HEAD) to a .patch file inside the project
yocto_build / yocto_task / yocto_clean	BitBake builds and tasks with full pre-flight checks (build dir, MACHINE/DISTRO, disk space, root check) and mandatory user confirmation
yocto_recipe_info / yocto_show_vars	Read-only recipe metadata and evaluated BitBake variables via bitbake -e
device_tree_find_node / device_tree_find_property	Locate DTS nodes by label, name, path or compatible value; find property definitions
device_tree_validate / device_tree_diff	Structural validation (duplicate labels, undefined references, dtc-style reg/unit-address checks) and structural diff between two DTS files
analyze_log	Severity-classified log analysis (dmesg, journalctl, any log file: serial, boot, bitbake) with optional regex filter

Safety Layer (code, not prompt): every bash/powershell call from the agent passes through a command classifier before execution — rm -rf /, git push --force, dd ... of=/dev/..., mkfs, fork bombs and piping downloads into shells are blocked outright; mutating commands (git commit, bitbake, make, redirects to files, …) require user confirmation; unknown commands are treated as mutating, never silently allowed; without a UI (headless/RPC mode) confirmation-required commands are denied, not auto-approved. BitBake tools additionally enforce pre-flight checks and in-tool confirmation, and validate all names against shell injection.

CLI (embedded-pilot): doctor (environment check), project (project context), tools (tool list).

Not implemented yet

• Yocto/BitBake execution tools, device tree tools, log analysis (Phase 2)
• Serial / STM32 hardware tools (Phase 3), MCP server (Phase 4)
• Evaluation framework & benchmark suite (Phase 5)
• Nothing here has been verified on real hardware

Architecture (target)

                     User
                       │
                embedded-pilot CLI        (thin SDK wrapper)
                       │
                Pi Agent Runtime          (unmodified upstream)
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
     Context         Tools         Safety Layer
                        │            (tool_call interceptor)
                 ┌──────┼──────┐
                 ▼      ▼      ▼
              Yocto   Device   Git / Shell / Diagnostics
               DTS     Tree

Key design decisions (rationale in docs/):

1. Pi extension, not a fork — everything rides on Pi's public ExtensionAPI and SDK.
2. Safety Layer is code, not prompt — dangerous commands are blocked in a tool_call interceptor; the model cannot talk its way around it.
3. Small and deep — no LangChain/LangGraph/multi-agent/vector-DB until a benchmark proves they are needed.

Quick start (development)

# requirements: Node.js >= 22.19
npm install
npm run typecheck          # tsc --noEmit (strict)
npm test                   # vitest unit tests
npm run verify:extension   # loads the extension the way Pi does (jiti)
npm run verify:tools       # registers all tools through the real Pi SDK and checks them
pilot doctor               # environment check + project detection (after npm link)

End-to-end runs with a real LLM (requires a provider configured in ~/.pi/agent/models.json, see docs/development.md):

node scripts/verify-agent-run.mjs    # the agent answers a question using the git_status tool
node scripts/verify-safety-run.mjs   # a force-push attempt is blocked by the safety layer

Use the agent (after npm link, or npm run pilot inside the repo):

npm link        # one-time: puts `pilot` on your PATH
pilot           # starts the interactive agent with all 18 tools preloaded
pilot doctor    # environment check + project detection

Then, for example:

> 识别一下当前项目，为什么我的板子内存比预期少？

The agent will call embedded_project_info, then embedded_diagnostics, then inspect device trees — and every shell command it tries to run is filtered by the Safety Layer first.

Documentation

Document	Content
docs/pi-architecture.md	Research findings on Pi 0.84.4 internals (agent loop, tool system, extension API, SDK)
docs/roadmap.md	Phase 0-6 plan and current status
docs/development.md	Environment, dependency policy, workflow, API version notes

License

MIT — see LICENSE. Pi upstream remains the work of its authors; EmbeddedPilot uses it through its public API.