Sorting-hat
Sorting Hat (CLI: hat) is a clanker — an AI-powered file-naming CLI. Suggests descriptive filenames based on file contents, with an animated ASCII hat that thinks while streaming the LLM's reasoning tokens.
Stack: Shell. Public repo. Works with any OpenAI-compatible API — local (llama.cpp, Ollama, vLLM, LM Studio) or cloud (OpenAI, Together, etc.).
Supported formats
| Format | How it names |
|---|---|
| Text files (.txt, .md, .py, .json, .csv, etc.) | First 4000 chars sent to the LLM |
| Images (JPEG, PNG, SVG) | Base64-encoded, multimodal API |
| Images (WebP, BMP, TIFF, GIF) | Converted to PNG via Pillow, then as above |
| Audio (MP3, FLAC, OGG, AAC, WAV, M4A, Opus, WMA, AIFF, APE) | Named from embedded tags via ffprobe — not sent to the LLM
|
| Video (MP4, MKV, WebM, AVI, MOV, …) | Named from ffprobe metadata
|
| Lifeform | clanker |
Features
- Animated hat with drop animation, blinking eyes, streaming thought bubble.
- Auto-detects image / audio / video by magic bytes + extension.
--preview/-pprints a content snippet to stderr before the hat animation.- Handles reasoning / thinking tokens from Qwen, DeepSeek, etc.
- Quiet mode (
--quiet/-q). - Configurable reasoning: guard clause defaults to no thinking, naming uses thinking.
--nothinkdisables both,--fullthinkenables both. - Batch processing for entire directories.
- Guard clause skips already-descriptive filenames via a two-turn conversation (
--forceoverrides). --context/-cfor guided naming.- File metadata (EXIF, timestamps, MIME) in LLM context;
--no-metadatato disable. - Interactive rename with confirmation (
--yes/-yto auto-rename).