🐈‍⬛ POWERcat

🔭 Overview

POWERcat is a single-shot concatenator for bundling markdown and code into one clean text file. It's the feline cousin of Unix cat—polished for PowerShell, built for sharing code with recruiters, collaborators, and LLMs.

Breaking change (v2.0.0): POWERcat no longer includes .md files by default. This was an intentional, breaking change to avoid accidentally bundling documentation. To restore previous behavior, explicitly opt-in with -IncludeMarkdown or add -Extensions ".md". See ReleaseNotes for migration guidance.

✨ Features

• Stdout-first output: Outputs to stdout by default (Unix cat style); optional file writing via -OutputFile.
• Concatenation: Bundle multiple filetypes into a single output.
• Recursion: Include subdirectories with -Recurse.
• Token estimation: View character and estimated token count with -Stats for AI context planning.
• Markdown fences: Opt-in code fencing with -Fence for clean LLM/GitHub sharing.
• Header formats: Choose between Markdown, JSON, or YAML with -HeaderFormat for flexible parsing.
• Minification: Strip comments and blank lines with -Minify for lean, token-optimized bundles.
• Size filtering: Exclude files by size with -MinSize and -MaxSize to control output volume.
• Binary file detection: Automatically skips common binary formats to prevent errors.
• Extensions: No implicit defaults — opt-in. Use -IncludeMarkdown to include .md, or include types via switches (-Bash, -PowerShell, -HTML, -CSS, -Lua) or -Extensions.
• Sorting: Control file order with -Sort Name|Extension|LastWriteTime|Length.
• Catignore support: Exclude files and directories with a .gitignore-style catignore file.
• Aliases: Quick commands POWERcat, pcat, concat all point to Invoke-POWERcat.
• Native help: Full comment-based help via Get-Help Invoke-POWERcat.

🚀 Blasting Off

Install from PowerShell Gallery

Install-Module -Name POWERcat -Scope CurrentUser
Import-Module POWERcat

Run as a cmdlet

# Output to file (positional SourceDir)
Invoke-POWERcat "C:\Project" -OutputFile "C:\bundle.txt"

# Output to stdout (and pipe to file)
Invoke-POWERcat "C:\Project" | Out-File "C:\bundle.txt"

Aliases

POWERcat . -o out.txt                    # Write to file
pcat . | Out-File out.txt                # Pipe to file
concat . -r -f -p                        # Stdout with fences

Help

Get-Help Invoke-POWERcat -Full
Get-Help Invoke-POWERcat -Examples

Demos

See POWERcat in action:

Display help with the -h flag

Bundle files with -Stats and output to stdout

Write bundled files to .txt and view with nano

Pipe bundled bash files to bat for syntax highlighting

Pipe bundled output to lolcat for rainbow terminal fun

🧪 Examples

• Concatenate matching files to stdout (no implicit Markdown):

Invoke-POWERcat "C:\Project"
# Output streams to console; pipe to capture
Invoke-POWERcat "C:\Project" | Out-File bundle.txt

• Bundle for LLMs with minification, fences, and token stats:

Invoke-POWERcat "C:\Project" -Recurse -Minify -Fence -PowerShell -Stats

Output includes:

• Stripped comments and blank lines (lean for token limits)
• Code fenced blocks (markdown-aware)
• Token estimate (4 chars/token baseline):

=== POWERcat Statistics ===
Files processed:     15
Total characters:    45,230
Estimated tokens:    11,308 (4 chars/token baseline)
===========================

• Write to file with JSON headers for structured parsing:

Invoke-POWERcat "C:\Project" -o "C:\bundle.txt" -Recurse -HeaderFormat JSON -Lua

Output includes structured headers like {"file":"script.lua"} for better LLM parsing.

• Exclude large files to optimize for token limits:

Invoke-POWERcat "C:\Project" -Recurse -MaxSize 50KB -Bash

• Custom extensions and sorting:

Invoke-POWERcat "C:\Project" -o "C:\bundle.txt" -Extensions ".ps1",".json",".sh" -Sort Extension

• Use catignore to exclude directories:

Create a catignore file in your project:

node_modules/
.git/
*.log
bin/
obj/

Then run:

Invoke-POWERcat "C:\Project" -o "C:\bundle.txt" -Recurse

• View token estimation before bundling:

# Note: POWERcat no longer includes Markdown by default. Use `-IncludeMarkdown` to include `.md` files.
Invoke-POWERcat "C:\Project" -Recurse -Minify -Stats
# See: Files processed, Total characters, Estimated tokens
# Then decide: pipe to file, adjust MaxSize, or minify further

🗺️ Repo structure

This repo ships both a module and a standalone script for convenience:

• Module: src/POWERcat/POWERcat.psm1, src/POWERcat/POWERcat.psd1
• Script: scripts/POWERcat.ps1

Module usage:

Import-Module .\src\POWERcat\ -Force
Invoke-POWERcat . -o out.txt

Script usage:

.\scripts\POWERcat.ps1 . -o out.txt

Note: If you see scripts blocked, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser as admin or follow your org policy.

☄️ Why POWERcat?

Because recruiters, collaborators, and LLMs don't want a directory tree—they want one file, structured and readable. POWERcat makes your work portable, token-efficient, and a little stylish.

POWERcat vs. Standard cat

Standard cat or Get-Content:

# Just dumps all files end-to-end with no structure
Get-ChildItem -Recurse -Filter "*.ps1" | Get-Content
# Output: No file separators, no headers, unclear which code belongs where

POWERcat:

Invoke-POWERcat . -Recurse -Fence -PowerShell
# Output:
# --- File: script1.ps1 ---
#
# '''ps1
# function HelloWorld { Write-Host "Hello" }
# '''
#
# --- File: script2.ps1 ---
#
# '''ps1
# function GoodbyeWorld { Write-Host "Goodbye" }
# '''

The difference:

Feature	cat	POWERcat
Stdout output	✅	✅ (default)
File output (optional)	❌	✅
File headers	❌	✅ (Markdown/JSON/YAML)
Code fencing	❌	✅ (Markdown fences)
Minification	❌	✅ (strip comments)
Token estimation	❌	✅ (AI context planning)
Size filtering	❌	✅ (min/max size)
Exclusion patterns	❌	✅ (catignore support)
Sorting control	❌	✅ (by name, extension, size, date)
Multiple extensions	❌	✅ (flexible file type selection)
Binary safety	❌	✅ (auto-skip executables, images, etc.)

POWERcat is purpose-built for sharing code with recruiters, collaborators, and LLMs—creating readable, structured, token-aware bundles that respect context limits.

🛸 License

This project is licensed under the MIT License.

🪐 Recruiter's note

This isn't just a script—it's a demonstration of:

• Practical PowerShell scripting and automation
• Thoughtful parameter design and UX
• Clear documentation and branding
• Cross-platform compatibility (Windows, Linux, macOS)

If you're looking for someone who blends technical depth with creative polish, you've found him.

👽 Contact

Curious about my projects? Want to collaborate or hire for entry-level IT/support/dev roles? Shoot me an email or connect on GitHub—I reply quickly and love new challenges.

"Give someone a program, frustrate them for a day. Teach them to program, frustrate them for a lifetime." — Unknown