# 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/`](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/`](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/`](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/`](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-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. |
| [`notifyr/`](notifyr/) | `notifyr` | Sends **and reads** notifications on the homelab ntfy bus — alert a human, or check what the infra has been complaining about. |
| [`svg-maker/`](svg-maker/) | `svgc` | Builds SVG graphics from `.svgd` text descriptions (shapes, text, groups, color vars) with terminal preview, measurements and out-of-canvas warnings. Display via agent-helm: `helmd share out.svg`. |
| [`waitfor/`](waitfor/) | `waitfor` | Blocks until a shell condition holds (exit 0 + optional regex match) — replaces hand-rolled poll loops. `--then` hook composes with notifyr. |
| [`cronr/`](cronr/) | `cronr` | Recurring/one-shot jobs as systemd user timers that survive session exit and reboot. add/list/run/logs/rm, schedules validated by systemd-analyze. |
| [`giteactl/`](giteactl/) | `giteactl` | Gitea Actions runs, job logs (API/web/ssh+zstd fallback), `wait` (block until green) and `wait-quiet` (the "serialize heavy builds" rule), release assets. |
| [`fleet/`](fleet/) | `fleet` | One-shot homelab health snapshot: container states, disk fill and failed systemd units across hosts, via read-only commands. Exit 2 = findings. |

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>`).

## Agent-capability & homelab-admin tools

[`doc/tool-parity.md`](doc/tool-parity.md) compares the Google agent's
built-in tools with Claude Code's, and specs the CLI tools that close
the gaps so any agent gets the same capabilities via its shell tool.
Built so far: `notifyr`, `waitfor`, `cronr`, `giteactl`, `svgc`,
`fleet` (2026-08-07). Still on the list: `envaudit`, `reghelper`,
`pagepub`, `nbcell`, `wtreectl`, `fanout`. Build order and rationale
live there and in [`doc/plan.md`](doc/plan.md). Agy finds the tools
through the `agent-tools` skill in `~/.gemini/config/skills/`.

## Building

```bash
# 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