bitwisecook/bytecode-compare
.claude/skills/bytecode-compare/SKILL.md
Compare our compiler's bytecode output against tclsh reference disassembly (8.5, 8.6, 9.0). Use when verifying bytecode correctness, investigating instruction sequence differences, or checking that our codegen matches C Tcl.
$ install --global
skillsauthnpx skillsauth add bitwisecook/tcl-lsp bytecode-compareInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 3, 2026, 8:27 PM195.6s2 files scanned
SKILL.md
- name:
- bytecode-compare
- description:
- >
- allowed-tools:
- Bash, Read
Bytecode Comparison Skill
Compares the bytecode produced by our compiler pipeline (lexer → lowering → IR → CFG → codegen) against tclsh reference disassembly (8.5, 8.6, 9.0) for a set of 30 test snippets.
Usage
Run from the project root:
python3 .claude/skills/bytecode-compare/bytecode_compare.py [-v VERSION] <subcommand> [args...]
Options
| Flag | Description |
|---|---|
| -v, --version | Tcl version to compare against: 8.5, 8.6, 9.0 (default: 9.0) |
Subcommands
| Subcommand | Arguments | What it does |
|---|---|---|
| all | | Compare all 30 snippets, show summary table |
| diff | <snippet> | Detailed instruction-by-instruction diff for one snippet (e.g. 08_while) |
| summary | | One-line per snippet: match/mismatch with instruction counts |
| instructions | <snippet> | Side-by-side normalised instruction listing |
| refresh | | Regenerate our bytecode reference and re-compare |
| categories | | Group differences by category (variable access, jumps, opcodes, etc.) |
| versions | <snippet> | Compare one snippet against all Tcl versions (8.5, 8.6, 9.0) |
Interpreting Output
Summary mode
01_set_simple MISMATCH ours: 3 instrs 9.0: 4 instrs
03_expr_braced MATCH ours: 2 instrs 9.0: 2 instrs
22_puts_invoke MATCH ours: 4 instrs 9.0: 4 instrs
MATCH means identical normalised instruction sequences. MISMATCH means differences exist.
Diff mode
=== 08_while ===
9.0: (0) push1 0 # "i"
9.0: (2) push1 1 # "0"
9.0: (4) storeStk
ours: (0) push1 0 # "0"
ours: (2) storeScalar1 %v0 # var "i"
--- variable access: storeStk (name-based) vs storeScalar1 (LVT-indexed)
Categories mode
Groups all divergences into categories:
- Variable access: storeStk/loadStk vs storeScalar1/loadScalar1
- Jump encoding: relative offsets vs absolute PC
- Missing opcodes: opcodes tclsh uses that we don't emit
- Extra instructions: instructions we emit that tclsh doesn't
- Dead code: unreachable code differences
When to use
- After modifying
server/compiler/codegen.py— verify instruction sequences - After modifying lowering or CFG — check for regressions
- When investigating why a specific snippet diverges from tclsh
- Before committing codegen changes — run
summaryas a gate check
$ARGUMENTS
Related Skills
bitwisecook/tcl-optimise
development
VerifiedTrustedCommunity
Apply LSP optimiser suggestions to a Tcl file and explain why each optimisation is safe and beneficial. Covers constant folding, propagation, dead code elimination, strength reduction, and expression canonicalisation. Use when optimising Tcl code, improving .tcl file performance, refactoring Tcl scripts for efficiency, or applying language server optimisation suggestions.
34SKILL.mdUpdated Apr 3, 2026
bitwisecook/irule-optimise
development
VerifiedTrustedCommunity
Apply LSP optimiser suggestions to an F5 iRule and explain why each optimisation is safe and beneficial. Covers constant folding, propagation, dead code elimination, strength reduction, and expression canonicalisation. Use when optimising iRule code, improving iRule performance, applying F5 iRule optimisations, or refactoring iRules for efficiency.
34SKILL.mdUpdated Apr 3, 2026
bitwisecook/tk-create
development
VerifiedTrustedCommunity
Create Tk GUI code from a description with proper widget hierarchy. Generates the code, validates with the LSP analyser (including TK-specific checks), and iterates until clean. Use when creating Tk GUIs, generating Tcl/Tk code from descriptions, building Tk widget layouts, or scaffolding Tk applications.
29SKILL.mdUpdated Apr 3, 2026
bitwisecook/tcl-validate
development
VerifiedTrustedCommunity
Run full LSP validation on a Tcl file and produce a categorised report of all issues: errors, security, style, and optimiser suggestions. Use when validating Tcl code, linting .tcl files, checking Tcl script quality, or running static analysis on Tcl scripts.
29SKILL.mdUpdated Apr 3, 2026