Agclhx

Cross-platform binary editor CLI tool for AI automation and human use.

Features

• View: Display hex + ASCII data
• Write: Write hex data to specified position with verification
• Find: Search for hex patterns in files
• Fill: Fill byte ranges with fixed values
• Replace: Replace hex patterns globally or within ranges
• Patch: Apply batch modifications from patch files

Installation

pnpm install

Usage

# Default JSON output (machine-friendly)
agclhx <command> [options]

# Human-readable output
agclhx <command> [options] --human

# Save output to file
agclhx <command> [options] -o output.json

Commands

view

agclhx view <file> [--start offset] [--len length] [--cols columns]

write

agclhx write <file> --pos offset --hex "data" [--verify] [--allow-extend]

find

agclhx find <file> --hex "pattern"

fill

agclhx fill <file> --from start --to end --val byte_value

replace

agclhx replace <file> --src-hex "pattern" --dst-hex "replacement" [--start offset] [--end offset]

patch

agclhx patch <file> -f patch.txt

Patch File Format

0x00:11 22 33
0x02:44 55 66

Build

pnpm run build

Test

# Generate test file
python -c "data = bytes([0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]); open('test/test_sample.bin', 'wb').write(data)"

# Run tests
node main.js view test/test_sample.bin --human
node main.js write test/test_sample.bin --pos 4 --hex "FF FF FF FF" --verify --human
node main.js find test/test_sample.bin --hex "FF FF FF FF" --human
node main.js fill test/test_sample.bin --from 8 --to 15 --val 0 --human
node main.js replace test/test_sample.bin --src-hex "00 01" --dst-hex "99 99" --human
node main.js patch test/test_sample.bin -f test/patch.txt --human
node main.js view test/test_sample.bin --human

Error Codes

• 0: Success
• 1: File does not exist
• 2: Offset out of bounds
• 3: Invalid hex format
• 4: File IO error
• 99: Unknown action

License

MIT