/hsb-app

name: hsb-app
description: Discover and run Holoscan Sensor Bridge example applications on a connected devkit. Filters available apps by the user's platform, HSB software version, board type, and sensors. Supports timed execution, failure analysis, code-edit suggestions, and iterative re-runs.
author: "Holoscan Team <holoscan-team@nvidia.com>"
license: "Apache-2.0"
version: "1.0.0"
tags:
  - holoscan-sensor-bridge
  - hsb
  - running-app
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
disable-model-invocation: true
allowed-tools: Read,Write,Edit,MultiEdit,Grep,Glob,Bash
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  team: holoscan
  tags:
    - holoscan-sensor-bridge
    - hsb
    - running-app
  agents:
    - claude-code
    - codex

HSB Application Runner

Use this skill when the user wants to discover, select, and run Holoscan Sensor Bridge example applications on a devkit with a connected HSB board.

This skill assumes the devkit is already set up (SSH, demo container built, host configured, board connected). If setup is not complete, instruct the user to run `/hsb-setup` first.

This workflow runs applications inside the demo container. Only run it when the user explicitly invokes it.

Before you start — required gates (do these first, in order)

**Gate 1 — Read environment variables.** Before doing anything else, check these variables and print their resolved values to the user:

SSH_TARGET      Remote devkit login (e.g. nvidia@192.168.1.50). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint (optional).

**SSH_TARGET and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.**

**Gate 2 — Present the phase plan and get confirmation.** Before taking any action:

If the user's request already includes platform, board type, and sensors, also state upfront:

• You will scan `examples/` and filter apps by the user's sensor type and platform
• You will NOT add `--headless` automatically — only if the user explicitly requests it
• If the user specified a timeout (e.g., "60-second timeout"), state you will use that as the watchdog timeout
• Applications run inside the demo container via `docker run`, using `python3` for Python-based examples

Show the phase plan:

HSB App — Phase Plan
  Phase 0: Verify board connectivity and demo container readiness
  Phase 1: Discover user setup and select application to run
  Phase 2: Run application with monitoring, failure analysis, and iterative debugging
  Phase 3: Generate session report (with option to save)

Then ask explicitly: `Shall I proceed with Phase 0? [Y/n]` — do not start Phase 0 until the user confirms.

**Gate 3 — Fast path check.** After the user confirms in Gate 2, run this check before executing any Phase 0 commands:

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET \
  "grep _SESSION_VERIFIED /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || echo 'no session'"

If the output contains `_SESSION_VERIFIED=true`, skip Phase 0 and Phase 1 setup discovery — go directly to app selection and inform the user.

What this skill must do

1. Verify that the devkit is reachable over SSH, the HSB board is connected and responsive, and the demo container is available. Read the current FPGA version and board identity. 2. Interact with the user to understand their specific setup — repo location on the devkit, HSB software version, board type (Lattice, etc.), and connected sensors (e.g., dual IMX274, VB1940). Then scan the repository's user guide and `examples/` directory to build a list of applications compatible with the user's setup. Present the list and let the user choose an app to run. 3. Run the selected application inside the demo container, monitor output, and if the app fails, analyze the log output and guide the user through debugging — including suggesting code or environment edits and re-running the app. 4. Produce a summary report of the session — issues encountered, fixes applied, and outcome. Offer to save the report to a file.

Linux/Windows-friendly wrapper variables

Reuse the same environment variables from the `hsb-setup` and `hsb-flash` skills:

• `SSH_TARGET` for the remote login target (e.g. `nvidia@agx-thor-host`)
• `REMOTE_ROOT` for the remote working directory
• `REMOTE_SUDO` for privileged commands
• `REMOTE_SSH_OPTS` for additional SSH options
• `HSB_PLATFORM` as an optional platform hint

If these are set, notify the user of these settings and use them without re-asking.

Before Phase 0, print the resolved remote execution settings.

Mandatory interaction pattern

First run in a session (no prior verification)

When no valid session state exists, show the full phase plan:

• Phase 0: Verify board connectivity and demo container readiness
• Phase 1: Discover user setup and select application to run
• Phase 2: Run application with monitoring, failure analysis, and iterative debugging
• Phase 3: Generate session report (with option to save)

Then execute one phase at a time.

Subsequent runs in the same session (fast path)

When the session state file (`/tmp/.claude_hsb_app_session/state.sh`) exists **and** contains `_SESSION_VERIFIED=true`, the skill skips Phase 0 and Phase 1 setup discovery because connectivity and hardware were already verified. Instead, inform the user and jump directly to app selection:

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Board: HSB Lattice | FPGA: XXXX
  Platform: AGX Thor | HSB version: X.X.X
  Sensors: Dual IMX274

Proceeding directly to application selection.

Then execute:

• Phase 1 Steps 2–3 only (scan examples, present app list, user selects app)
• Phase 2: Run application
• Phase 3: Session report

When to re-run