agent-tools/README.md

agent-tools

Small, self-contained CLI tools built for AI agents to use during development work. Every tool is a single static Go binary with a text-first interface: input formats an agent can read and write directly, and output (names, errors, previews) explicit enough that the agent understands the result without opening an image viewer.

Tool	Binary	What it does
pixel-sprite-maker/	spritec	Turns .sprite text files (palette + character grid) into PNG/JPG/SVG pixel art, up to 256x256 px per sprite. Combines several sprites into sprite sheets / animation strips whose file names document the layout (walk_8x8_4x1.png = 8x8 px frames, 4 columns, 1 row).
mesh-tool/	mesht	Creates, inspects and edits 3D models (OBJ + STL). ASCII multi-view rendering + measurements (bbox, volume, watertightness) let an agent see a model, edit it (scale/rotate/mirror/merge/primitives) and verify the result.
bitmap-font-maker/	fontc	Turns .font text files (pixel glyph grids, proportional widths) into font atlases (PNG + JSON metrics) and renders text strings to PNG or the terminal.
sfx-maker/	sfxc	Synthesizes retro game sound effects (sfxr-style) from .sfx text presets to 16-bit WAV: waves, envelope, pitch slides, vibrato, arpeggio, filters. Deterministic, with built-in presets (jump, coin, laser…).
hitbox-tool/	hitbox	Scans sprite sheet PNGs and writes per-frame collision boxes as JSON from the alpha channel. Understands the spritec sheet naming convention including upscaled sheets.

Each tool has its own folder, its own README with the full format/CLI reference, its own tests and its own dev branch (dev/<tool>).

Building

# Arch/Garuda prerequisite:
sudo pacman -S go

cd <tool>/ && go build -o build/<binary> .    # per tool
go test ./...                                 # per tool

VS Code: Terminal → Run Build Task — build builds every tool into its own <tool>/build/ folder; per-tool build <tool> and test <tool> tasks also exist.

CI / releases

.gitea/workflows/release.yml runs on every push to master/main on the self-hosted runner: tools whose folders changed are tested, built for linux x64 + arm64 (the Pi5), and published to a rolling release per tool on the repo's release page:

• tag pixel-sprite-maker-latest → assets spritec-linux-x64, spritec-linux-arm64, checksums.txt
• tag mesh-tool-latest → assets mesht-linux-x64, mesht-linux-arm64, checksums.txt

A manual workflow_dispatch run builds all tools regardless of diffs.

Branch layout

• main — stable, releases are built from here
• dev/pixel-sprite-maker, dev/mesh-tool — per-tool development branches