strix-halo-optimizations/AGENTS.md

AGENTS.md — Agent Workflows

Read CLAUDE.md first for safety rules and technical context.

Common Workflows

Add a Detection Function

1. Add the function to lib/detect.sh following detect_* naming convention
2. If it reads sysfs, use $GPU_SYSFS (auto-detected) with a 2>/dev/null fallback
3. Wire it into scripts/audit/quick-glance.sh (display) and/or scripts/audit/system-report.sh (JSON output)
4. If it has an optimal value, add a check to scripts/optimize/verify.sh
5. Validate: make audit and bin/audit --json | python3 -m json.tool

Add a Benchmark Backend

1. Add the toolbox entry to BENCH_PATHS associative array in both scripts/benchmark/run-baseline.sh and scripts/benchmark/run-suite.sh
2. Map the toolbox name → llama-bench binary path (Vulkan: /usr/sbin/llama-bench, ROCm: /usr/local/bin/llama-bench)
3. If ROCm, the ENV_ARGS logic already handles ROCBLAS_USE_HIPBLASLT=1
4. Add the toolbox to refresh-toolboxes.sh in the toolboxes repo
5. Validate: make benchmark-setup then make benchmark

Add an Optimization Script

1. Create scripts/optimize/my-optimization.sh sourcing lib/common.sh (and detect.sh / format.sh as needed)
2. Add root check at top if the script modifies system state: [[ $EUID -ne 0 ]] && { log_error "Requires root"; exit 1; }
3. Add a corresponding case to bin/optimize
4. Add a Makefile target
5. Add verification criteria to scripts/optimize/verify.sh
6. If the optimization is reversible, add rollback logic to scripts/optimize/rollback.sh
7. Document in docs/optimization.md

Add a Monitoring Metric

1. In scripts/monitor/log-metrics.sh, cache the sysfs path at startup (avoid per-sample globbing)
2. Read with read -r var < "$SYSFS_PATH" 2>/dev/null || var=0 (no subshells in the hot loop)
3. Add the column to the CSV header and the echo line
4. Update the CSV schema in docs/architecture.md

File Responsibility Map

Want to change...	Touch these files
What make audit shows	scripts/audit/quick-glance.sh, lib/detect.sh
JSON audit output	scripts/audit/system-report.sh, lib/detect.sh
Dashboard layout	scripts/monitor/dashboard.sh
Metric collection	scripts/monitor/log-metrics.sh
Benchmark parameters	scripts/benchmark/run-baseline.sh, run-suite.sh
Result comparison	scripts/benchmark/compare.sh
Kernel params	scripts/optimize/kernel-params.sh, lib/detect.sh (recommended values)
Optimization checks	scripts/optimize/verify.sh, scripts/audit/quick-glance.sh
Shared utilities	lib/common.sh (logging), lib/format.sh (output), lib/detect.sh (hardware)
External links	docs/references.md (single source of truth)

Dependencies by Workflow

Workflow	Requires
Audit	bc, python3
Monitor	tmux, amdgpu_top or nvtop, btop or htop
Benchmark	toolbox, podman, GGUF models in data/models/, python3
Optimize	sudo/root, grubby or grub2-mkconfig, tuned-adm, python3