luxonis-inspect

name	luxonis-inspect
description	Inspect a running DepthAI or OAK pipeline with oakctl inspect (frames, depth, detections, topics). Use when a pipeline is already running and you need live evidence.

Luxonis Inspect

See what a running pipeline is actually producing. A topic list is not proof of correct behavior. Process liveness is not proof.

Done when

Opened image or parsed message evidence shows the claimed pipeline behavior, or blocked with the missing endpoint, topic, output, or decoder and one next action.

Never invent oakctl flags from memory.

Best source first: the Luxonis MCP tools (surfaced names vary by host), then the exact example or doc source they return, then https://docs.luxonis.com/llms.txt, then observed behavior; memory is only for general reasoning. For oakctl commands and flags, the installed oakctl --help outranks docs and MCP: the local version (possibly older or beta) defines what is possible here, so work from it and suggest an oakctl update when it lacks something current docs describe. If observed host or device behavior contradicts docs or MCP, trust the observation and note the conflict. If offline, work from oakctl --help and local examples and name which facts are unverified.

If AGENTS.md is missing, or oakctl is missing, name luxonis-workspace and follow it, then continue. Do not copy its procedure.

Read docs/brief.md, docs/device.md, and source when present. Also read legacy root PROJECT_BRIEF.md and DEVICE.md if present. None is required. Treat docs/device.md as setup notes; trust live state. Do not start a greenfield interview. If the product is wrong, mention luxonis-app.

1. Name the claim

State the narrow claim and the minimum topics that can test it. Separate pipeline structure, sensor/model/depth/crop/track semantics, application state, and final output outside DepthAI.

2. Establish the endpoint

Run current oakctl inspect --help and the relevant subcommand help before constructing commands. Confirm flag names and placement against that help; inspection is evolving.

• Local host pipeline: no target option (local default).
• Another host: --url ws://<host>:<port>.
• Standalone OAK 4 app: --device <selector> or an exact --url.

Call the selected option <target-options>. It is empty, --url <url>, or --device <selector>. The endpoint is never an unnamed positional argument.

RVC2 cannot run a standalone OAK App; inspect the host running its pipeline. Never infer localhost because oakctl happens to run locally.

3. Prepare the application only when needed

For an explicitly read-only inspection, do not edit source or restart the application. If required topics are absent, report the missing instrumentation and the smallest proposed source change. Source instrumentation is allowed only when this session is already allowed to change code; then read references/instrumentation.md.

4. Discover and capture

Start or attach to the application in the intended topology. Use bounded commands of this shape, then match the installed syntax if it differs:

oakctl inspect topics <target-options> --timeout 10s
oakctl inspect pipeline <target-options> --timeout 10s
oakctl inspect snapshot --out <evidence-dir> <target-options> --timeout 10s
oakctl inspect frames <image-topic> --count 3 --out <evidence-dir> <target-options> --timeout 10s
oakctl inspect dump <data-topic> --count 5 <target-options> --timeout 10s

Use --seconds for a bounded temporal sample when count is a poor fit. Never leave an unbounded inspect process running.

Topics may appear only after the first message. Produce representative input before diagnosing an absent topic.

Create a unique run directory under evidence/ (not under docs/), with a separate subdirectory per image topic so common frame filenames cannot overwrite each other. Next session does not depend on evidence/.

5. Interpret evidence

Open every image and parse every JSON/JSONL record used for a claim. Check dimensions, encoding, scene content, crop framing, overlay alignment, labels, confidence, coordinates, units, timestamps, track state, and whether the observation matches the claimed behavior.

A graph and topic list are structural evidence. Snapshot values may be unsynchronized and are not a substitute for a temporal sample. Unsupported encodings may need another bounded observation path; do not change the application merely to conceal an inspector limitation.

When code changes are needed, keep the capture command stable, change one cause, restart, and rerun the same capture.

Guardrails

• Never deploy, stop, restart, reset, update, adopt, flash, or change device settings as part of a read-only inspection.
• Never run competing processes against one device.