---
name: esp-vision-development
description: Use ESP-VISION device capabilities and official firmware/API knowledge for the specific task, with the plugin's bundled local device CLI.
---

# ESP-VISION capabilities

Choose only the capabilities needed for the user's request. Use the `esp-vision-knowledge` MCP for authoritative ESP-VISION APIs, chip support, firmware guidance, and examples. Use the bundled CLI for local device discovery, inspection, configuration, control, firmware operations, Python execution, files, captures, watches, or batch plans. A documentation question does not require a device connection; a device operation does not require a documentation lookup unless an API or firmware detail is uncertain.

Invoke the installed plugin copy with Node and the absolute path to `cli/device-cli.mjs`. Resolve the plugin root from the current host's installed plugin path, not the user's project working directory. Codex hook commands can use `PLUGIN_ROOT`; Claude Code hook commands can use `CLAUDE_PLUGIN_ROOT`. If a shell session does not expose either path, read the local marketplace/plugin path with the host's native list command and use the installed copy. Do not invoke a global `esp-vision-device` command, `npx`, or a separate MCP device server. The standalone `@esp-vision/device-cli` package is also available to users who want the CLI outside this plugin; the plugin carries its own versioned copy.

Use `node <plugin-root>/cli/device-cli.mjs --help` for command syntax. Inspect candidates without probing when discovery is needed. Select a serial path or TCP endpoint explicitly; never choose one automatically. Before a requested device change, inspect the selected device when identity or firmware capabilities matter. Keep device-specific claims grounded in the connected device or the official Knowledge MCP.

Each CLI operation connects to the selected device and disconnects in cleanup when the operation finishes. Inspection, capture, watch, configuration and native file uploads use a connection that does not probe or interrupt the Python REPL. Python execution and REPL-backed file operations can interrupt an existing program; use them only when that interruption is intended. `watch` keeps the connection for its requested duration and disconnects on completion or cancellation. If another tool or client currently owns the device, do not force takeover or retry blindly; ask that owner to stop and release its session before starting a CLI operation. After the CLI command ends, wait for its cleanup and verify the result before handing control to another owner.

Use `--json` when structured output helps. The CLI writes one versioned JSON envelope to stdout; status, progress, Python output, and diagnostics are NDJSON on stderr. Binary reads and captures write to the requested local file and return metadata. For batch plans, report which operations completed and which failed.

Cancellation releases the local connection but does not undo device changes or prove that a started script stopped. A timeout, cancellation, lost response, or unknown execution result can leave a side effect uncertain. Inspect the device state before retrying; do not repeat a command whose outcome is unknown. Follow the user's requested target and authorization, and ask only when the endpoint, board, or requested side effect cannot be determined safely.

For a continuous application, upload its script and dependencies before starting it with `python --path <device-path> --completion start`, without `--timeout`. A successful start result confirms that the VM entered the script runner; it does not prove application initialization or later execution succeeded. Use passive captures while the app runs, then `control --action stop` (without `--mode`), then read progress files. `files list/read/remove/mkdir` and Python REPL commands can interrupt the running app. For continuous applications or camera/LCD acceptance, read [application workflow](references/application-workflow.md) for an executable sequence and evidence criteria.

Python stdout is bound to its original EV-MUX session: a new `watch` cannot reattach to a previous session's Python output. Use foreground `python --completion wait` when live Python output is required; a bounded `watch` observes events and diagnostics available to its current session. Inspection fields `runtime.scriptRunning` and `runtime.run` track execution initiated by the current SDK session; a new CLI process cannot use them to determine whether a detached device program is running. `runtime.vmReady` means the VM has started, not that it is idle. Preserve application cleanup handlers and explicitly stop a running application before replacement.

When development exposes a reproducible official package, tool, firmware or knowledge problem, retain a brief local feedback note: requested outcome, versions, minimal commands, expected/observed results, relevant evidence, workaround and what remains unverified. Distinguish confirmed defects from supported constraints and application mistakes. Use available facts and mark missing details unknown; do not make the user fill gaps before recording the report. Continue the original task when a workaround permits it.

Offer the user three reporting choices for a confirmed official problem: anonymous report, GitHub issue, or no report. Show the proposed report and attachments and obtain explicit authorization before transmitting them. Use the repository's issue-template fields where available. Check that an official anonymous submission tool actually exists; if unavailable, label that choice as draft-only and do not invent an endpoint or claim submission. Do not silently upload logs, images or bug reports.