v1.1.0

New features

• WezTerm support for -I thumbnails and clickable filenames — previously iTerm2-only. WezTerm implements the same OSC 1337 inline image protocol, so -I's thumbnails and -1/-l's clickable file:// hyperlinks now both work there too.
• Quick Look thumbnails for Office documents — Word/Excel/PowerPoint files (.docx/.xlsx/.pptx, and the legacy .doc/.xls/.ppt) now get an actual rendered first-page/sheet/slide preview via macOS's Quick Look, not just a generic icon. --ql-ext controls which extensions are tried (off, all, or a custom comma-separated list).
• -N shorthand for --scale=N — e.g. -2 for --scale=2, combinable with other short flags in any position (-Il2, -2Il, etc.).
• ImageMagick fallback for -I on Linux — sips, used to shrink an oversized thumbnail before sending it, is macOS-only. On Linux (and WSL/Coreutils for Windows), macls now uses ImageMagick's magick/convert instead when available, so large images get shrunk there too instead of always being sent at full resolution.

Improvements

• -I thumbnails for large images are shrunk locally before transmission (sips on macOS, ImageMagick elsewhere) instead of sending the full-resolution original — much faster over a directory of large photos/scans.
• -1/-l output with -I streams incrementally as each entry's thumbnail becomes ready, instead of waiting for every thumbnail in the directory before printing anything.
• PDF thumbnails are now always rasterized/shrunk regardless of file size, so they render at a consistent size instead of varying based on which side of a size threshold they happened to land on.
• Fixed crashes when run on Windows.

Bug fixes

• Fixed -l entries being misaligned when real ls localizes its "total" header line (e.g. 合計 under a Japanese locale instead of total) — this was also the root cause of -I thumbnails sometimes appearing to belong to the wrong entry. The header is now detected by line count instead of matching the English word, so it's immune to locale/translation.
• Added a safety net that skips drawing a -I thumbnail (rather than risk drawing a technically-correct thumbnail next to the wrong entry's line) if a -l line's real data can't be matched back up to its entry.
• Fixed filenames containing an embedded control character (e.g. a literal newline) being silently split into bogus multiple entries, corrupting the listing. A symlink's target text is now also sanitized/quoted the same way an entry's own name already was.

🤖 Generated with Claude Code

v1.0.0

macls.py v1.0.0

First public release of macls.py — a dependency-free, single-file Python 3 script that's a drop-in colorized replacement for macOS's ls.

Highlights

• Modification-time gradient — a name's foreground color fades along a recency gradient (5 min / 30 min / 1 hour / 2 hours / 1 day / 1 week / 1 month / older), so the file you're mid-edit on jumps out at a glance.
• Finder tags as background color — tag a file in Finder, see it colored in the terminal (--tag=bg/dot/str).
• Compact columns that don't collapse — --columns=compact (the default) lets one long filename span multiple column slots instead of stretching every column.
• Striped columns — --stripe tints alternating columns (or rows, in -l/-1) for easier scanning.
• Inline image thumbnails — -I shows a thumbnail next to image files using iTerm2's inline image protocol.
• Clickable filenames — every name is an OSC 8 hyperlink to its file:// URL.
• Suffix coloring — --suffix-color=type colors -F's / @ * = | indicators by file type.
• Quoting — --quote wraps names with spaces/shell metacharacters in shell-safe quotes.
• GNU-style option/path ordering: options and paths can be freely mixed, e.g. macls.py file.txt -l.
• Falls straight back to the real /bin/ls for any option it doesn't support.

Requirements

• Python 3.9+ (macOS's built-in /usr/bin/python3 works)
• macOS (Finder tags and -I thumbnails are macOS/iTerm2-only; basic listing and coloring also work on Linux, including WSL2)
• iTerm2 recommended, for -I thumbnails and clickable filenames

Install

chmod +x macls.py

Put it on your PATH, or alias it in your shell config:

alias ls='/path/to/macls.py -BF --stripe --suffix-color=type --fg-mode=date --tag=bg --quote'

Full option and color reference: macls.md.

License

MIT — see LICENSE.