Look up Tensix architecture, instruction, or LLK implementation details across architectures. Orchestrates sage agents in parallel.
Debug compilation or runtime errors in LLK kernels. Infers architecture and kernel type from path.
Get structured porting guidance when moving a kernel between architectures. Launches sages for source and target, reads test harness.
Enforce safe bash scripting practices when writing, reviewing, or fixing shell scripts. Covers quoting, arrays, conditionals, arithmetic, redirections, strict mode, and static analysis. Use when editing .sh/.bash files, reviewing shell scripts, fixing shellcheck warnings, or writing new bash code.
Guides test-first workflows for bugs and features: write a minimal failing test that encodes contracts and clear failure messages, confirm the gap is not already covered, implement and document the fix, then verify green. Use when fixing bugs with tests, adding features via TDD, writing regression tests, or when the user asks for red-green-refactor or test-driven development.
| name | run-test |
| description | Run LLK tests using the test runner agent. Never run pytest directly. |
| user_invocable | true |
Wraps .claude/scripts/run_test.sh, which serialises simulator access (flock), kills stale port processes, sets TT_UMD_SIMULATOR_PATH, and exposes count / compile / simulate / run subcommands. Agents and Claude must never call pytest directly.
/run-test <test_file> [--arch <arch>] [options]
Examples:
/run-test test_eltwise_binary_quasar.py --arch quasar
/run-test test_sfpu_square_quasar.py --arch quasar --k Float16
/run-test test_eltwise_binary_quasar.py --arch quasar --rerun
/run-test test_eltwise_binary_quasar.py --arch quasar --compile-only
/run-test test_sfpu_square_quasar.py --arch quasar --no-split
/run-test test_eltwise_binary_quasar.py --arch quasar --maxfail 5
/run-test test_matmul_quasar.py --arch quasar --test-id 'test_matmul_quasar.py::test_matmul[math_fidelity:LoFi-...-format:Float16->Float16-...]'
<test_file> — required, e.g. test_sfpu_square_quasar.py--arch <arch> — quasar, blackhole, wormhole. Required unless inferable (see below)--k <expr> — pytest -k filter (applied to both compile-producer and consumer so the two phases stay aligned)--test-id <id> — single parametrize ID (single-quotes/brackets safe)--maxfail <N> — stop after N failures--rerun — skip compile, simulate only (uses prior compile-producer artifacts)--compile-only — compile-producer only, no simulate--no-split — combined compile+run in one pytest invocation (issue-solver tests)--port <N> — simulator port (default 5556)--timeout <secs> — pytest timeout ceiling (default 600)--progress — manual-debug aid: emit a [progress] <phase>: elapsed=Ns, last_output=Ns ago line to stderr every 30s during compile and simulate. Off by default; pass when you suspect a hang and want to see whether a phase is alive but slow vs. truly stuck. Pair with --progress-interval <secs> to tune.If --arch is not provided, infer in this order:
tests/python_tests/quasar/ → quasar*_quasar.py / *_blackhole.py / *_wormhole.py → use thattest_matmul.py): ask the userParse the test file, arch (or infer), and options.
Pick a subcommand for the script:
--compile-only → compile--rerun → simulate--no-split → run --no-split (combined invocation)run (compile then simulate)Spawn the llk-test-runner agent. Its system prompt covers env setup, script invocation, exit-code diagnosis, and output formatting — just pass the inputs:
Agent tool:
subagent_type: "llk-test-runner"
description: "Run tests: {test_file} ({arch})"
prompt: |
test_file: {test_file}
arch: {arch}
command: {compile|simulate|run|count}
options: {whatever applies from --k / --test-id / --maxfail / --no-split / --port / --timeout}
Relay the agent's verdict to the user. On FAIL or COMPILE_FAIL, suggest /debug-kernel. On ENV_ERROR or HANG, surface the agent's diagnosis and stop — don't auto-retry (the same hang will reappear, and env errors need a human fix).
When run_test.sh detects a silicon hang (exit 5), after killing the
consumer tree and before resetting the device, it runs .claude/scripts/llk_triage.py.
Output appears in the RUN_LLK_TESTS_HANG block as:
--- llk-triage ---
=== LLK TRIAGE ===
Arch: blackhole
Location: 0,0
== Mailbox state ==
Unpacker @ 0x... = 0x000000FF (KERNEL_COMPLETE)
Math @ 0x... = 0x00000000 (incomplete)
...
Hung kernel threads: Math
== Tensix state (per RISC) ==
{ ... PC, soft-reset, status per RISC ... }
--- end llk-triage ---
Standalone use (e.g., to inspect a wedged device manually):
source tests/.venv/bin/activate
python3 .claude/scripts/llk_triage.py --arch blackhole \
[--location 0,0] [--device-id 0]