Feeding Codebases to AI: lscat, a Bash Power Tool

Every serious AI-assisted session starts the same tedious way: pasting files into a prompt, one by one, losing the directory structure that gives them meaning. lscat exists to end that ritual — a Bash utility that walks a tree, prints a structured overview, and concatenates file contents with customizable delimiters, ready for humans and AI workflows alike.

Structure first, contents second

An AI model reasons better when it sees the map before the territory. lscat prints a tree overview up front, then each file under a clear header, so the model always knows where the code it is reading lives. Context windows are large; orientation is still scarce.

Defaults that respect the pipe

The whole tool configures from flags with sane starting points:

DELIMITER="---"
INCLUDE_HIDDEN=false
COMPRESS=false
HEADER_TYPE="tree" # tree, ls, ls-R, none

Headers come in tree, ls, or ls-R flavors — or none at all when tokens matter more than maps. Colors switch off automatically when output goes to a file, because ANSI codes in a saved prompt are just noise.

Compression is a dial, not a switch

Feeding a whole repository can blow past context limits, so compression runs in modes: strip comments and blank lines for a light pass, or squeeze harder when the codebase is huge. The point is never to hide code — it is to spend tokens on logic instead of whitespace.

Prune at the find level

Skipped directories are pruned during traversal, not filtered afterward — node_modules and build output never even get walked. On a monorepo that is the difference between seconds and minutes, and between a focused prompt and a polluted one.

MCP makes it a citizen

Beyond the terminal, lscat plugs into AI workflows through the Model Context Protocol, so agents can pull oriented codebase snapshots on demand instead of asking the human to paste files. The tool meets the models where they already work.

Takeaway

Prompt quality is input quality. A hundred lines of shell that package context well will outperform any model upgrade — build the funnel before blaming the brain.