If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/icedland/iced shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 5w ago
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live icedland/iced repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/icedland/iced.

What it runs against: a local clone of icedland/iced — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in icedland/iced | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of icedland/iced. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/icedland/iced.git
#   cd iced
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of icedland/iced and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "icedland/iced(\\.git)?\\b" \\
  && ok "origin remote is icedland/iced" \\
  || miss "origin remote is not icedland/iced (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "build/build-rust" \\
  && ok "build/build-rust" \\
  || miss "missing critical file: build/build-rust"
test -f "build/build-dotnet" \\
  && ok "build/build-dotnet" \\
  || miss "missing critical file: build/build-dotnet"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "src/UnitTests/Intel/Decoder/DecoderTest64.txt" \\
  && ok "src/UnitTests/Intel/Decoder/DecoderTest64.txt" \\
  || miss "missing critical file: src/UnitTests/Intel/Decoder/DecoderTest64.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/icedland/iced"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

iced is a high-performance x86/x64 instruction decoder, disassembler, assembler, and encoder library supporting 16/32/64-bit Intel and AMD instruction sets. It decodes raw binary machine code into semantic instruction objects and can re-encode them, achieving >250 MB/s throughput while maintaining correctness against xed, gas, objdump, masm, nasm, and other reference implementations. Monorepo with language-specific implementations: src/rust/ contains the canonical Rust implementation (iced-x86, iced-x86-py, iced-x86-js, iced-x86-lua), src/csharp/Intel/ has C# bindings, src/java/iced-x86/ has Java bindings. Test data (instruction opcodes, decoder/formatter test vectors) lives in src/UnitTests/Intel/ as .txt files (DecoderTest16/32/64.txt, OpCodeInfos.txt). Build orchestration via build/ scripts handles cross-language compilation.

Systems programmers, reverse engineers, binary analysis tool developers, and compiler/JIT engineers who need to parse, analyze, or generate x86/x64 machine code in Rust, .NET, Java, Python, JavaScript (WebAssembly), or Lua without writing low-level byte-parsing logic.

Highly mature and production-ready. The codebase spans ~75 MB across Rust (29M LOC), C# (25M LOC), and Java (16M LOC) implementations with extensive test coverage via files like src/UnitTests/Intel/Decoder/DecoderTest*.txt and continuous CI/CD via .github/workflows/build.yml and release.yml. Last activity indicates active maintenance and regular releases to crates.io, NuGet, Maven, and PyPI.

Low risk for stability: single-maintainer (icedland) but well-tested against multiple reference implementations. Risk comes from the multi-language build complexity (build/build-* scripts) and the large generated code surface from instruction tables—changes to instruction encoding are high-touch. No obvious unmaintained dependencies visible, but the breadth of language bindings (6 languages) creates coordination overhead for updates.

The repo maintains active release cycles (visible via .github/workflows/release.yml) and CI builds (build.yml). Specific file structure shows ongoing formatter work (src/UnitTests/Intel/Formatter/Fast/) with options testing and symbol resolver tests. Python wheel building (build/py-build-wheels-linux.sh, build/ci-py-build-wheels.sh) suggests active Python packaging work.

Clone and check the language-specific README:

git clone https://github.com/icedland/iced.git
cd iced
# For Rust: cd src/rust/iced-x86 && cargo build
# For .NET: cd src/csharp && dotnet build
# For Java: cd src/java/iced-x86 && mvn build
# For Python: cd src/rust/iced-x86-py && pip install -e .

Daily commands: Language-dependent; start with the canonical Rust implementation:

cd src/rust/iced-x86
cargo test          # run tests
cargo build --release  # build optimized library
cargo doc --open    # view API docs

For other languages, see language-specific build scripts in build/ or README files in src/{csharp,java,rust/iced-x86-py}.

• README.md — Core project overview describing iced as a blazing-fast x86/x64 disassembler, assembler, decoder, and encoder supporting multiple language bindings and instruction formats.
• build/build-rust — Primary Rust build script; every contributor must understand the baseline compilation and testing pipeline for the native Rust implementation.
• build/build-dotnet — Defines .NET binding generation and compilation; essential for contributors working on cross-language bindings.
• .github/workflows/build.yml — CI/CD pipeline orchestrating decoder, encoder, formatter, and cross-platform validation; critical for understanding test coverage and release gates.
• src/UnitTests/Intel/Decoder/DecoderTest64.txt — Core 64-bit decoder test vectors; demonstrates the specification for instruction decoding and validation that all implementations must pass.
• src/UnitTests/Intel/Encoder/OpCodeInfos.txt — Encoder opcode metadata and test cases; foundational specification for instruction encoding across bitwidth variants.
• src/UnitTests/Intel/Formatter/Fast/Test64_Default.txt — Reference formatter output for the default (Fast) x64 syntax; ensures consistency and correctness of instruction-to-string conversion.

Add Support for a New x86 Instruction

1. Add the instruction opcode definition and metadata to the encoder reference; update OpCodeInfos.txt with the new opcode, mnemonic, operand types, and encoding rules (src/UnitTests/Intel/Encoder/OpCodeInfos.txt)
2. Add 64-bit decoding test vector for the new instruction with hex input and expected decoded output (src/UnitTests/Intel/Decoder/DecoderTest64.txt)
3. Add 32-bit and 16-bit variants if applicable (src/UnitTests/Intel/Decoder/DecoderTest32.txt)
4. Add expected formatter output for default (Fast) syntax in 64-bit mode (src/UnitTests/Intel/Formatter/Fast/Test64_Default.txt)
5. Add expected Intel syntax formatting output (src/UnitTests/Intel/Formatter/Intel/Test64_MemDefault.txt)
6. Add expected AT&T/Gas syntax formatting output (src/UnitTests/Intel/Formatter/Gas/Test64_NoSuffix.txt)
7. Run build/build-rust to validate decoder, encoder, and formatter against test vectors; fix implementation if tests fail

Add a Formatter Option or Style

1. Define the new formatter option metadata and defaults in the appropriate formatter module configuration (src/UnitTests/Intel/Formatter/Fast/Options2.txt)
2. Add test vectors showing the formatter output with the new option enabled for 64-bit instructions (src/UnitTests/Intel/Formatter/Fast/Test64_Default.txt)
3. If the option affects other syntaxes (Intel, Gas), add variants in their respective test directories (src/UnitTests/Intel/Formatter/Intel/OptionsResult.txt)
4. Add symbol resolver tests if the option affects address/operand symbol resolution (src/UnitTests/Intel/Formatter/Fast/SymbolResolverTests.txt)
5. Rebuild all language bindings via build/build-rust, build/build-dotnet, etc., to ensure API surface and tests propagate

Extend Test Coverage for an Instruction Mode

1. Add comprehensive test cases for miscellaneous 64-bit instruction encodings (edge cases, prefixes, operand combinations) (src/UnitTests/Intel/Decoder/DecoderTestMisc64.txt)
2. Add corresponding 32-bit and 16-bit miscellaneous tests if the instruction is multi-mode (src/UnitTests/Intel/Decoder/DecoderTestMisc32.txt)
3. Add memory operand edge-case tests (scaled indices, 64-bit addresses, rex prefixes) (src/UnitTests/Intel/Decoder/MemoryTest64.txt)
4. Add instruction info validation tests to confirm semantics (register uses, memory reads/writes, flags modified) (src/UnitTests/Intel/Formatter/InstructionInfos64_Misc.txt)
5. Run the full CI pipeline via .github/workflows/build.yml locally or push to validate across all language bindings

• Rust (core implementation) — Provides memory safety, performance (no GC), and zero-cost abstractions for bit-level instruction manipulation and cache-friendly decoder tables
• Multi-language bindings (.NET, Python, Java, JS/WASM, Lua) — Extends reach to developers across ecosystems while maintaining single authoritative Rust implementation to avoid instruction semantics divergence
• Test-driven specification (text fixture files) — Encodes instruction semantics as executable specifications independent of language; enables fuzzing and cross-validation against external disassemblers
• GitHub Actions CI/CD — Automates multi-platform builds, regression testing, and release distribution to 6+ package ecosystems in a single workflow

• Single Rust implementation with language bindings vs. native implementations per language
  • Why: Avoids semantic divergence and 6× maintenance burden; binding code is thin FFI
  • Consequence: Rust must be built as a shared library; adds toolchain dependency but ensures correctness parity

1. Code generation dependency: Rust is the canonical source; C# and Java are generated/manually ported from it. Changes to instruction encoding require updating both. 2. Test data format: .txt files in src/UnitTests/ use a specific semicolon-delimited format (hex bytes; expected registers; expected operands; etc.) that is NOT documented inline—see existing test files for examples. 3. Multi-language sync: Python/JavaScript/Lua bindings are thin wrappers around Rust via FFI (PyO3, wasm-bindgen); breaking Rust API changes break all bindings simultaneously. 4. Build order: build/build-rust must complete before building C# and Java, and generated code is committed to the repo (not just CI artifacts).

• x86 Instruction Encoding (VEX, EVEX, legacy prefixes) — iced must correctly parse variable-length instruction formats (1–15 bytes) with overlapping prefix rules (REX, VEX, EVEX) to extract opcode and operands; this is the core decoding challenge.
• State Machine Decoding — iced uses deterministic finite state machines (visible in decoder tables) rather than large lookup tables to handle x86's complex opcode branching rules and decode instructions in a single pass without backtracking.
• ModRM Byte (Mod/Reg/R/M field) — The ModRM byte encodes addressing modes and register operands in x86; iced must correctly parse this per-instruction to extract register and memory operand information.
• SIB Byte (Scale/Index/Base for addressing) — 32/64-bit addressing often requires a SIB (Scale-Index-Base) byte following ModRM to encode complex memory operands; iced must conditionally parse this based on ModRM state.
• CPUID Feature Flags (instruction availability) — iced includes metadata for which CPU feature flags enable each instruction (SSE, AVX, AVX512, etc.); essential for validating instruction validity against a target CPU and for disassembler filtering.
• Formatter Customization (masm/nasm/gas/Intel dialects) — iced supports pluggable formatters that produce assembly syntax in different styles; users must choose the correct formatter dialect matching their use case (e.g., Intel syntax for MASM, AT&T syntax for GNU tools).
• Code Generation from Instruction Tables — iced's build pipeline (build/build-rust) generates decoder/encoder tables and API stubs from src/UnitTests/Intel/Encoder/OpCodeInfos.txt; understanding this prevents duplicate definitions and keeps multi-language bindings in sync.

• capstone-engine/capstone — Direct competitor; also a multi-architecture disassembler (x86, ARM, MIPS, etc.) with Python/Java/C# bindings, but iced is x86-focused and significantly faster.
• keystone-engine/keystone — Companion to Capstone; an assembler framework. Iced combines assembler + disassembler in one library, whereas Keystone is dedicated to assembly only.
• intel/XED — Intel's official x86 encoder-decoder; iced is tested against XED for correctness and uses XED-style opcode naming/formatting, making it a conceptual reference implementation.
• radareorg/radare2 — Binary analysis framework that uses disassemblers (like iced could) as plugins; represents a downstream user of instruction decoding libraries.
• icedland/disas-bench — Performance benchmark suite maintained alongside iced; compares decoding speed (>250 MB/s claim) against xed, capstone, objdump, and other tools.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive Lua language binding tests in src/UnitTests/

The repo has build scripts for Lua (build/build-lua) and test files for Rust, .NET, Java, and Python formatters (src/UnitTests/Intel/Formatter/Fast, Gas, etc.), but there are no visible Lua-specific unit tests. Given that iced supports Lua as a first-class language binding, adding unit tests would ensure parity with other language bindings and catch integration issues early.

• [ ] Create src/UnitTests/Lua directory structure mirroring existing formatter test patterns
• [ ] Port decoder tests from src/UnitTests/Intel/Decoder/*.txt to Lua test format
• [ ] Add Lua-specific formatter tests for Fast and Gas syntax variants
• [ ] Integrate Lua tests into build/build-lua CI script to run on pull requests

Add JavaScript/Node.js binding tests and CI workflow

The build system includes build/build-js script, but there are no visible unit tests or GitHub Actions workflow for JavaScript/Node.js unlike other language bindings (Python has build/ci-py-build-wheels.sh, .NET/Java/Rust have their own workflows). This is a gap in CI coverage for one of the supported language targets.

• [ ] Create src/UnitTests/JavaScript directory with decoder/encoder/formatter test files
• [ ] Add .github/workflows/build-js.yml workflow to test Node.js binding on each PR
• [ ] Port existing Intel decoder test cases from src/UnitTests/Intel/Decoder/*.txt to JavaScript format
• [ ] Update build/build-js to include test execution steps

Add missing x86 instruction edge-case tests for 16-bit mode

The decoder test files show DecoderTest16.txt exists but Code.32Only.txt and Code.64Only.txt files suggest incomplete coverage. Some decoder features may have gaps in 16-bit instruction testing, especially around legacy/rare instruction encodings that are critical for correct disassembly of legacy code.

• [ ] Review src/UnitTests/Intel/Decoder/DecoderTest16.txt for edge cases not covered
• [ ] Identify untested 16-bit specific instructions (e.g., real mode segmentation, protected mode transitions)
• [ ] Create new test file src/UnitTests/Intel/Decoder/DecoderTest16_EdgeCases.txt with rare/legacy instruction encodings
• [ ] Add corresponding entries to Code.16Only.txt if missing
• [ ] Run full test suite to ensure no regressions

• Add missing decoder test cases for rare/undocumented x86 instructions by examining src/UnitTests/Intel/Decoder/Code.NotDecoded*.txt (which lists unimplemented opcodes) and creating test vectors in DecoderTest64.txt following the existing hex-bytes;expected-output format.
• Improve formatter test coverage by adding symbol resolver tests to src/UnitTests/Intel/Formatter/Fast/SymbolResolverTests.txt for address-to-name mapping edge cases (e.g., overlapping symbols, negative offsets) and validating formatter output with custom symbol providers.
• Write documentation or examples for the Python binding (src/rust/iced-x86-py/) showing how to use the assembler DSL (e.g., asm.mov(eax, edx) from README) in practical code analysis scripts, since only the Rust README has detailed examples.

The iced x86 disassembler project shows a reasonably secure structure with no obvious critical vulnerabilities in the provided file listing. However, the analysis is limited by missing dependency manifests and build script contents. Key observations: (1) No hardcoded credentials visible in file names, (2) No obvious injection attack vectors in the file structure (primarily a low-level binary analysis library), (3) Multi-language support increases maintenance burden but is not inherently insecure, (4) Comprehensive test coverage is positive. Recommendations: Implement automated dependency scanning in CI/CD pipeline, document security practices, review build scripts and GitHub Actions workflows for supply chain security, and maintain an up-to-date Software Bill of Materials (SBOM).

• Medium · Missing Dependency Lock File Information — Root directory / Dependencies. No package lock files (Cargo.lock, package-lock.json, etc.) were provided in the analysis. This makes it impossible to verify if specific vulnerable versions of dependencies are being used. The repository targets multiple languages (Rust, .NET, Java, Python, Lua) which increases the attack surface. Fix: Ensure all lock files are committed to version control and regularly audit dependencies using tools like cargo audit, npm audit, pip audit, and Maven dependency-check.
• Low · Test Data Files Without Clear Source Validation — src/UnitTests/Intel/. The codebase contains numerous test data files (DecoderTest*.txt, MemoryTest*.txt, etc.) in src/UnitTests/. While these appear to be legitimate test fixtures, there is no visible validation mechanism documented for their integrity or origin in the provided file structure. Fix: Document the source and validation process for all test data files. Consider using checksums or signed commits to verify test data integrity.
• Low · Build Script Analysis Required — build/. Multiple build scripts are present (ci-install-rust.sh, py-build-wheels-linux.sh, ci-py-build-wheels.sh, npm-fix-json.py) but their content was not provided for review. Shell scripts and Python scripts can potentially introduce supply chain risks if they execute external commands without proper validation. Fix: Review all build scripts for: (1) use of hardcoded URLs, (2) unvalidated external command execution, (3) proper error handling, (4) secure credential handling.
• Low · GitHub Actions Workflow Configuration Not Fully Analyzed — .github/workflows/. CI/CD workflows exist (.github/workflows/build.yml, release.yml) but their content was not provided. Insecure workflow configurations could allow privilege escalation, secret exposure, or unauthorized artifact publication. Fix: Review GitHub Actions workflows for: (1) proper secret management, (2) least privilege RBAC, (3) artifact signing, (4) dependency pinning in actions, (5) protection rules on main branch.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.