esp-claw: Instructions file for Codex

Agents.md

This file provides guidance to agents when working with code in this repository.

Project Overview

ESP-Claw is an ESP-IDF firmware project for running an AI agent framework on Espressif IoT devices. The main application is application/edge_agent/; reusable firmware components live under components/. The repo also contains board definitions, build-time FATFS content, documentation, and the embedded device settings UI.

Development Commands

Export ESP-IDF before firmware work:

. $IDF_PATH/export.sh

Generate board manager files and build from the app directory:

cd application/edge_agent
idf.py bmgr -c ./boards -b esp32_S3_DevKitC_1
idf.py build
idf.py flash monitor

Docs site:

cd docs
pnpm install
pnpm build
pnpm dev

Embedded settings UI:

cd application/edge_agent/components/http_server/frontend_source
pnpm build
pnpm typecheck

High-Level Architecture

Boot and Runtime Flow

The main entry point is application/edge_agent/main/main.c.

Core Data Flow

1. IM channels, scheduler jobs, Lua scripts, startup hooks, or CLI commands publish events or submit requests.
2. claw_event_router matches events against the DATA root's router_rules/router_rules.json and can call capabilities, run scripts, run the agent, send messages, emit events, or drop events.
3. claw_core builds context from memory, session history, skills, and other providers; calls the configured LLM backend; executes capability tool calls; persists context; and returns responses.
4. Outbound messages are routed back through registered IM bindings or local/web channels.

Key Subsystems

• Application shell (application/edge_agent/main/main.c, components/common/app_claw/): boot flow, storage paths, capability registration, Lua module registration, CLI, and agent startup.
• Agent core (components/claw_modules/claw_core/): request queue, context building, LLM backend runtime, tool-call loop, media inference, interrupts, context persistence, and response delivery.
• Event router (components/claw_modules/claw_event_router/): declarative event routing and actions backed by router rules in FATFS.
• Capability registry (components/claw_modules/claw_cap/): common registration and dispatch layer for model-callable capabilities.
• Capabilities (components/claw_capabilities/): concrete agent capabilities such as Lua execution, files, IM platforms, MCP, skill management, router management, scheduler, session management, time, HTTP requests, web search, system, and LLM inspection.
• Memory (components/claw_modules/claw_memory/): session history, profile/long-term memory providers, memory persistence, request gating, and stage notes.
• Skills (components/claw_modules/claw_skill/, component skills/ directories): user-facing skill documents and activation state.
• Apps (components/common/app_registry/, SYSTEM/DATA apps/ directories): standalone Lua App packages consumed by the System UI Launcher.
• Lua modules (components/lua_modules/): Lua drivers and higher-level modules for hardware, media, HTTP server, storage, threading, JSON, board manager, and capability calls.
• Board manager (application/edge_agent/boards/): board metadata, peripheral YAML, board setup code, board defaults, optional local components, and optional board FATFS overlays.
• FATFS images (application/edge_agent/fatfs_image/): build-time source trees for the read-only SYSTEM image and writable DATA seed image.
• HTTP config service (application/edge_agent/components/http_server/): local device configuration server and embedded frontend.