jetson-thor-cli

Agent and CLI for operating NVIDIA Jetson Thor (Blackwell-based robotics/edge-AI compute, Orin's successor) — provisioning, inference, and on-device ops.

What you get

• An agent-first CLI cited from teken's python-cli reference — the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching resident prompt file (AGENTS.colleague.md, since this template runs backend: colleague).
• The canonical guildmaster skill kit (14 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run thor whoami             # identity from culture.yaml
uv run thor learn              # self-teaching prompt (add --json)
uv run thor status             # machine-wide scope, anomalies first
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Machine scope (Jetson Thor host telemetry)

Jetson Thor is the system, so these read-only verbs sit at the top level:

They have zero runtime dependencies — kernel telemetry is read from /proc and /sys, while nvidia-smi, docker, and ip are shelled out and degrade gracefully (a missing tool reports available: false and still exits 0). doctor remains the health gate.

On real Thor hardware nvidia-smi is present but thin: it reports name/utilization.gpu/utilization.memory but temperature.gpu, power.draw, and clocks.sm all come back [N/A] — the iGPU doesn't expose those counters through NVML the way a discrete card does. gpu backfills those three fields from stable sysfs nodes instead (devfreq for clock, the *gpu* thermal zone for temperature, the VDD_GPU hwmon rail for power), and records which fields it backfilled in source (nvidia-smi+sysfs). Because Thor's GPU shares one unified memory pool with the CPU — no discrete VRAM — nvidia-smi reports memory.total/memory.used as [N/A] too; gpu instead sums per-process compute-app memory and points at thor memory for the shared pool rather than inventing a VRAM number:

uv run thor gpu
uv run thor power

Swap management

Swap inspection is read-only; the grow command is a dry-run by default — re-run with --apply to mutate. All commands support --json.

uv run thor swap status
uv run thor swap grow 64G      # dry-run: prints the plan, changes nothing
uv run thor swap history --window 1h --top 5
uv run thor swap sample

Per-process history collection via systemd timer

Per-process memory and swap history accrues only when thor swap sample runs on a schedule. Here's a systemd service and timer pair:

# /etc/systemd/system/jetson-thor-swap-sample.service
[Unit]
Description=Sample per-process swap/memory for jetson-thor-cli
[Service]
Type=oneshot
ExecStart=/usr/bin/env thor swap sample

# /etc/systemd/system/jetson-thor-swap-sample.timer
[Unit]
Description=Periodic thor swap sample
[Timer]
OnBootSec=2min
OnUnitActiveSec=10min
Persistent=true
[Install]
WantedBy=timers.target

Enable with sudo systemctl enable --now jetson-thor-swap-sample.timer. Note that system-level CPU/mem/swap trend already comes from sysstat/sar; this timer only adds the per-process layer.

Monitoring (monitor) — AI-free webhook watchdog

monitor turns the collectors into a deterministic, always-on watchdog. It evaluates the same numbers against configurable thresholds and POSTs to a generic webhook when a catastrophe condition crosses — and again when it clears (edge-triggered, so a standing condition doesn't spam). No AI, no new dependencies (urllib does the POST).

uv run thor monitor config --init     # scaffold ~/.config/jetson-thor/monitor.json
export JETSON_THOR_WEBHOOK_URL=https://…  # or put webhook_url in the config
uv run thor monitor check             # dry run: what's firing right now
uv run thor monitor config            # show resolved config + thresholds

Watches memory %, swap %, disk %, hottest sensor, GPU temp, load-per-core, I/O contention (iowait % + blocked processes), container health, and subsystem availability. Thresholds live in the config (~/.config/jetson-thor/monitor.json; null disables a check); webhook_format is generic (default), slack, or discord.

When monitor run starts (the systemd ExecStart), it POSTs a one-shot "started watching" liveness alert — so a watchdog that silently fails to come up is noticed by the absence of its heartbeat, not just the absence of an alert. A failed startup POST is logged, never fatal. Set notify_on_start: false in the config to disable it.

Make it your own

1. Rename the package jetson_thor/ and the jetson-thor-cli CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

Apache 2.0 — see LICENSE.