macls.py

A single-file, dependency-free Python 3 script that can replace the ls command. Runs on macOS and Linux.

Japanese/日本語版: README-ja.md

Features

Modification-time gradient

Where standard ls colors filenames by file type, macls.py colors them by what actually changed recently: a name's foreground fades along a recency gradient, bright for a file you just touched and dim for one you haven't opened in months.

Every name is colored by how recently it changed — 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, with no need for -t or a mental timestamp comparison.

Finder tags as background color (macOS)

Tag a file in Finder, see it in the terminal:

• With --tag=bg (the default), the most recently added tag's color becomes the entry's background. Any other tags show as small dots after the name.
• With --tag=dot, no background is used — every tag shows as a small dot after the name instead.
• With --tag=str, every tag's name is appended after the entry as a bracketed list, e.g. report.pdf [Work, Urgent], colored to match each tag.

Compact columns that don't collapse

Conventional ls -C sizes every column to the single longest name in the listing — one long filename and the whole grid degrades toward one column. macls.py's default --columns=compact instead lets a longer filename span multiple column slots on its own, keeping the rest of the grid tight.

--columns=classic	--columns=compact

Striped columns

--stripe tints alternating columns (or rows, in -l/-1) so a wide listing stays easy to scan line-by-line. It accounts for the --columns=compact layout too: an entry that spans multiple column slots still stripes as a single band, based on the column it starts in.

Inline image thumbnails (iTerm2/WezTerm)

With -I, image files (.png, .jpeg, .pdf, etc.) show a thumbnail next to their name using iTerm2's inline image protocol (also supported by WezTerm) — no open or separate viewer needed.

Word/Excel/PowerPoint documents (.docx/.xlsx/.pptx/.doc/.xls/.ppt) get a thumbnail too, via macOS's Quick Look. --ql-ext adjusts which extensions get one: off disables Quick Look thumbnails, all tries every non-image extension, or a comma-separated list (e.g. --ql-ext=md,rtf) adds extensions on top of the default list.

By default, the thumbnail is a single row; you can enlarge it with the --scale=N option (or its -N shorthand, e.g. -2 for --scale=2), though it only takes effect with -1 or -l — multi-column output ignores it.

Clickable filenames

Every filename shown by macls.py is a hyperlink to its file:// URL. In iTerm2, Cmd-click opens it; in WezTerm, just click.

On iTerm2, filenames are shown with an underline to indicate a hyperlink. You can disable underlining in iTerm2 settings (Settings > Advanced > Underline OSC 8 hyperlinks to off).

Suffix coloring

--suffix-color=type colors -F's / @ * = | indicators by file type.

Quoting

--quote wraps names containing spaces or shell meta-characters in shell-safe quotes, so a listing can be pasted straight back into a command line.

Easy to deploy

macls.py is implemented in a single Python file. No external module or compilation is required. It works by just dropping macls.py into a directory in your PATH.

And more

• -B bolds directory names
• --group-directories-first lists directories first
• --theme/--base-fg tune the gradient for light or dark terminal backgrounds
• If unsupported options are passed, falls straight back to the real ls

Requirements

• Python 3.9+ (recent macOS's /usr/bin/python3 should work)
• iTerm2 or WezTerm recommended, for -I thumbnails and clickable filenames
• On Linux, ImageMagick (magick or convert on PATH) is optional but recommended for -I: it's used to shrink large thumbnails before sending them, the way sips does on macOS. Without it, -I still works, just slower for large images.

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'

Usage

./macls.py
./macls.py -la ~/Desktop
./macls.py -I -1 --scale=2 ~/Pictures
./macls.py -Il4 ~/Pictures
./macls.py --stripe --tag=str

Full option and color reference: macls.md.

How it works

Enumerating/sorting directories and -l's long-format output are delegated to the system ls(1), so they never drift from real ls behavior. Everything else — Finder tag lookup, recency colors, display width, multi-column layout — runs in pure Python 3 with no external processes or third-party packages.

Acknowledgments

Most of this program was written by Claude Code.

License

MIT — see LICENSE.