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/JesusFreke/smali 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.

AVOID — Stale and unlicensed — last commit 2y ago

• 17 active contributors
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{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 JesusFreke/smali repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JesusFreke/smali.

What it runs against: a local clone of JesusFreke/smali — 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 JesusFreke/smali | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | Last commit ≤ 871 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JesusFreke/smali. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JesusFreke/smali.git
#   cd smali
#
# 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 JesusFreke/smali and re-run."
  exit 2
fi

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 871 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~841d)"
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/JesusFreke/smali"
  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).

smali/baksmali is an assembler/disassembler for the Android dex bytecode format used by the Dalvik VM. It converts between human-readable smali assembly syntax and compiled .dex binary files, enabling reverse engineering, modification, and analysis of Android APKs. The project supports the full dex specification including annotations, debug info, line numbers, and all instruction formats. Multi-module Gradle project: baksmali/ directory contains the main disassembly logic with Adaptors/ subdirectory providing formatting for different bytecode structures (instructions, debug info, annotations, try-catch blocks). Core classes: Baksmali.java (entry point), BaksmaliOptions.java (configuration), ClassDefinition.java (class output), MethodDefinition.java (method output). Depends on dexlib2 project (imported as :dexlib2 module) for dex file parsing.

Android reverse engineers, security researchers, and app developers who need to disassemble APKs into readable smali code, modify bytecode, or reassemble it back into dex format. Also used by build systems and obfuscation tools that manipulate Android binaries.

Production-ready and actively maintained. The codebase shows 3.5M lines of Java and 3M lines of smali test code, indicating mature test coverage and real-world validation. Repository has been actively developed for 10+ years with regular updates, making it the de facto standard tool in the Android reverse engineering community.

Low risk for core functionality, but single-maintainer (JesusFreke) introduces sustainability concerns. Dependencies are minimal (guava, jcommander, antlr_runtime, dexlib2) and well-established. The dex format is relatively stable, but new Android versions occasionally introduce bytecode extensions requiring updates. Check GitHub issues for any format compatibility gaps with latest Android versions.

Based on file structure, active development areas include: (1) Debug info formatting in baksmali/src/main/java/org/jf/baksmali/Adaptors/Debug/ with LocalFormatter.java and related debug method items, (2) Instruction disassembly with InstructionMethodItemFactory.java and format-specific handlers, (3) Command infrastructure with multiple command classes (DisassembleCommand, DeodexCommand, DumpCommand, etc.) suggesting CLI feature expansion. Check GitHub for recent PRs targeting Android 12+ dex extensions.

git clone https://github.com/JesusFreke/smali.git && cd smali && gradle build

Daily commands: Build only: gradle build. No runtime execution of the project itself — baksmali is a library/tool typically invoked via: java -jar baksmali.jar disassemble input.dex -o output_dir/ (after building and packaging).

• baksmali/src/main/java/org/jf/baksmali/Baksmali.java: Main entry point and orchestrator; coordinates disassembly workflow from dex loading through class/method/instruction output
• baksmali/src/main/java/org/jf/baksmali/BaksmaliOptions.java: Configuration object holding all disassembly options (debug info, line numbers, register info, code items, etc.); essential for understanding customization points
• baksmali/src/main/java/org/jf/baksmali/Adaptors/MethodItem.java: Core interface for all bytecode elements (instructions, labels, try-catch, debug info); every disassembled item extends this with writeTo(Writer) implementation
• baksmali/src/main/java/org/jf/baksmali/Adaptors/Format/InstructionMethodItem.java: Concrete MethodItem for individual dex instructions; formats register operands, offsets, and mnemonics into smali syntax
• baksmali/src/main/java/org/jf/baksmali/Adaptors/MethodDefinition.java: Orchestrates disassembly of a single method; coordinates instruction ordering, label generation, debug info insertion, and exception handling
• baksmali/src/main/java/org/jf/baksmali/Adaptors/ClassDefinition.java: Top-level class disassembly orchestrator; writes class declaration, annotations, fields, and methods; generates output file
• baksmali/src/main/java/org/jf/baksmali/Adaptors/CommentingIndentingWriter.java: Custom Writer wrapper that handles smali syntax indentation, comment insertion, and output formatting; all disassembly output flows through this
• baksmali/src/main/java/org/jf/baksmali/Adaptors/Debug/LocalFormatter.java: Formats debug local variable information (register-to-name mappings); critical for readable decompilation with variable names

For instruction formatting: edit baksmali/src/main/java/org/jf/baksmali/Adaptors/Format/InstructionMethodItem.java or create new format handler in Format/ subdir. For debug info: modify baksmali/src/main/java/org/jf/baksmali/Adaptors/Debug/*.java (e.g., LineNumberMethodItem.java for line mapping). For annotations: edit baksmali/src/main/java/org/jf/baksmali/Adaptors/AnnotationFormatter.java. For new CLI commands: create a new class extending DexInputCommand in baksmali/src/main/java/org/jf/baksmali/ and register in command dispatcher. Start with understanding MethodItem interface — all bytecode elements implement it with a writeTo(Writer) method.

1. dexlib2 dependency versioning: baksmali is tightly coupled to a specific dexlib2 version; mismatches cause silent format issues. Always build as complete gradle project, never mix jar versions. 2) Odex format legacy code: UnresolvedOdexInstructionMethodItem.java indicates support for obsolete Odex bytecode; this path is rarely tested. 3) Register info generation: PreInstructionRegisterInfoMethodItem and PostInstructionRegisterInfoMethodItem require analysis context; running without proper analysis options produces incomplete register type info. 4) Output directory handling: ClassDefinition writes files directly; ensure output directory is writable and has sufficient space for large APKs (can generate >100MB of smali). 5) Character encoding: CommentingIndentingWriter uses system default encoding; explicitly set UTF-8 via BaksmaliOptions or environment for consistent output on different platforms.

• DEX (Dalvik Executable) format — baksmali's entire purpose is to parse and emit this binary format; understanding dex structure (class definitions, method pools, bytecode sections) is prerequisite for any modification
• Smali assembly syntax — baksmali generates smali code; you must understand register notation (v0-v15), instruction mnemonics, and type descriptors to read disassembled output
• Visitor pattern with MethodItem hierarchy — Core architectural pattern in baksmali; every bytecode element (instruction, label, debug info, try-catch) is a MethodItem subclass that renders itself via writeTo(); understanding this enables adding new output formats
• Type descriptors and method signatures — baksmali formats types as strings (e.g., 'Ljava/lang/String;', '(II)V'); incorrect descriptor handling causes invalid smali syntax. Critical for field and method output formatting
• Debug information encoding in dex — Debug info (line numbers, local variable names) is encoded as delta sequences in dex; baksmali's Debug/ adaptor classes decode and reconstruct this; understanding deltas is key to fixing debug output bugs
• Odex (Optimized DEX) format — Legacy optimization format used in older Android versions; baksmali includes UnresolvedOdexInstructionMethodItem.java to handle Odex files, though this path is increasingly unused
• ANTLR grammar parsing — baksmali likely uses ANTLR runtime (in dependencies) for parsing smali syntax when assembling; understanding grammar rules explains parsing constraints

• JesusFreke/dexlib2 — Core dependency of baksmali; handles low-level dex binary parsing and structure representation; must understand dexlib2 types to work on baksmali disassembly logic
• google/android-classyshark — Alternative Android bytecode browser/analyzer; overlaps with baksmali's reverse-engineering use case but provides GUI and different output formats
• iBotpeaches/Apktool — Builds on baksmali and dexlib2 to provide complete APK unpacking/repacking; the primary end-user tool that non-specialists use instead of calling baksmali directly
• skylot/jadx — Java decompiler for Android; competes with baksmali+smali by converting dex directly to Java source instead of smali assembly, targeting higher-level readability
• google/android-security-and-privacy-year-in-review — Google's official documentation of dex format evolution; essential reference for understanding bytecode format changes that baksmali must support across Android versions

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 unit tests for BaksmaliFormatter and BaksmaliWriter

The formatter module (baksmali/src/main/java/org/jf/baksmali/formatter/) has only 2 classes but no corresponding test files in baksmali/src/test/. The BaksmaliFormatter and BaksmaliWriter are critical for output formatting and likely have complex edge cases (indentation, comment handling, special characters in identifiers). Adding unit tests here would improve code quality and catch regressions.

• [ ] Create baksmali/src/test/java/org/jf/baksmali/formatter/BaksmaliFormatterTest.java with tests for various smali syntax elements
• [ ] Create baksmali/src/test/java/org/jf/baksmali/formatter/BaksmaliWriterTest.java testing output buffering and line-ending edge cases
• [ ] Add test fixtures for annotations, debug info, and complex method signatures to validate formatting correctness

Add unit tests for all Adaptor classes covering MethodItem implementations

The Adaptors directory contains 25+ implementation classes (AnnotationFormatter, various MethodItem types, Debug subclasses) but test coverage appears limited to basic DexTest and AnalysisTest. These Adaptors are responsible for rendering specific dex structures (try-catch blocks, debug info, annotations, instructions) and need dedicated tests for edge cases like empty catch blocks, malformed debug info, and nested annotations.

• [ ] Create baksmali/src/test/java/org/jf/baksmali/Adaptors/CatchMethodItemTest.java testing try-catch rendering with various exception types
• [ ] Create baksmali/src/test/java/org/jf/baksmali/Adaptors/AnnotationFormatterTest.java with tests for complex annotation structures and nested annotations
• [ ] Create baksmali/src/test/java/org/jf/baksmali/Adaptors/Debug/DebugMethodItemTest.java covering local variable scoping and line number sequences

Add integration tests for Command classes with real dex file outputs

The codebase has 13+ Command classes (DisassembleCommand, DeodexCommand, DumpCommand, ListClassesCommand, etc.) but no visible integration tests validating command-line behavior and output correctness. These commands form the public API and need tests ensuring they properly handle edge cases (empty dex files, malformed inputs, missing boot classpath for deodex).

• [ ] Create baksmali/src/test/java/org/jf/baksmali/DisassembleCommandTest.java with test dex files and assertions on output structure/content
• [ ] Create baksmali/src/test/java/org/jf/baksmali/DeodexCommandTest.java testing with boot.oat/classes.dex scenarios and validating deobfuscation correctness
• [ ] Create baksmali/src/test/java/org/jf/baksmali/ListCommandTest.java (parent class) with parameterized tests for ListClassesCommand, ListMethodsCommand, ListStringsCommand, etc. validating list output format and filtering

• Add unit tests for baksmali/src/main/java/org/jf/baksmali/Adaptors/Format/SparseSwitchMethodItem.java and PackedSwitchMethodItem.java — these switch table formatters lack dedicated test coverage; create test cases for edge cases like empty switches and negative offsets
• Implement verbose logging output in baksmali/src/main/java/org/jf/baksmali/Baksmali.java — add optional debug logging at class/method/instruction level to help users troubleshoot disassembly issues; see AnalysisArguments.java for logging pattern
• Document the MethodItem rendering order contract in baksmali/src/main/java/org/jf/baksmali/Adaptors/MethodDefinition.java — add inline comments explaining why labels, debug info, and instructions must be interleaved in specific order; this is non-obvious and causes bugs in similar tools

The baksmali/baksmali project is a legitimate DEX disassembler with a reasonable security posture. No critical vulnerabilities were identified in the provided codebase structure. However, the incomplete build.gradle file prevents full dependency vulnerability assessment. Main concerns are: (1) unverified dependency versions, (2) lack of visible input validation for potentially malicious DEX files, and (3) resource handling best practices. As a tool that processes untrusted binary input (DEX files), implementing robust input validation and resource limits is recommended. The project appears well-maintained with comprehensive test coverage, which is a positive security indicator.

• Medium · Incomplete Dependency Analysis — baksmali/build.gradle. The build.gradle file shows incomplete dependency declarations. The line 'processResources.inputs.pro' appears truncated, suggesting the file content is incomplete. This makes it difficult to fully assess dependency security status. Common dependencies like 'guava', 'jcommander', and 'antlr_runtime' should be verified for known CVEs. Fix: Verify the complete build.gradle file is provided. Run 'gradle dependencyCheck' or use OWASP Dependency-Check to identify vulnerable dependency versions. Ensure all transitive dependencies are reviewed for security updates.
• Low · ProGuard Dependency in Build Script — baksmali/build.gradle. The buildscript includes ProGuard gradle plugin (depends.proguard_gradle). While ProGuard is a legitimate tool, ensure it's sourced from official repositories and that the specific version used does not have known vulnerabilities. Fix: Verify ProGuard gradle plugin version is up-to-date and sourced from mavenCentral(). Document the specific version constraints used.
• Low · No Input Validation Documentation — baksmali/src/main/java/org/jf/baksmali/. The codebase processes DEX files (binary format) with multiple command handlers (DisassembleCommand, DeodexCommand, etc.). While baksmali is a legitimate disassembly tool, there's no visible input validation or sanitization in the file structure for potentially malformed DEX files. Fix: Implement robust validation for DEX file format compliance before processing. Add fuzzing tests for malformed input handling. Document security assumptions about input trustworthiness.
• Low · Resource Handling in File Processing — baksmali/src/main/java/org/jf/baksmali/Adaptors/. The presence of ClassDefinition, MethodDefinition, and FieldDefinition classes suggests file I/O operations. Incomplete file resource management or improper exception handling could lead to resource leaks or DoS vulnerabilities when processing large or malicious DEX files. Fix: Implement try-with-resources for all file I/O operations. Add resource limits for processing (max file size, max iterations). Implement proper exception handling and resource cleanup.

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.