cagg — Code Aggregator

Bundles every relevant text/code file of a repository into a single output file, each preceded by a clear header showing which file follows:

-------------- src/index.js -----------------
1: 'use strict';
2:
...

Built for feeding a codebase to an LLM or for a quick, readable overview of a project — the output is kept as small as possible (no unnecessary blank lines, no binaries, no build artifacts).

Example

An example aggregation of the source code for the tool is included. See agg.txt.

Install

npm install -g cagg

Usage

cagg                       # aggregate CWD into ./agg.txt
cagg -i path/to/project     # aggregate a different folder
cagg -o context.md          # change output name/extension
cagg -a                     # use absolute paths in headers instead of CWD-relative
cagg --no-line-numbers      # don't prefix lines with numbers
cagg --max-size 1           # skip files larger than 1 MB
cagg --max-lines 2000       # skip files with more than 2000 lines

Ignoring files

By default, cagg ignores an extensive built-in list of common clutter: .git, node_modules, build/dist output, caches, lockfiles, IDE folders, OS files, and common binary/media file types (images, fonts, archives, documents, ...). Files that don't look like text (checked by content, not just extension) are always skipped and reported.

• --no-ignore — disable all ignoring; every file is included. Prints a warning since this will likely pull in dependencies and binaries.
• --ignore-patterns "pattern1,pattern2" — supply your own .gitignore-style patterns. This replaces the built-in default list. Can be repeated / combined with commas.
• --ignore-file <path> — same idea, but patterns come from a file (e.g. point it at your real .gitignore). Also replaces the default list.
• If the current directory has a .gitignore, its entries are automatically merged into whichever ignore list is active (default or custom). Disable this with --no-merge-gitignore.

The output file itself is always excluded from its own aggregation.

All options

-i, --input <path>            input directory to scan (relative to CWD or absolute) (default: ".")
-o, --output <path>           output file name/path (default: "agg.txt")
-a, --absolute-paths          use absolute paths in file headers instead of CWD-relative paths
    --no-ignore                disable all ignoring; include every file (prints a warning)
    --ignore-patterns <patterns>  comma-separated gitignore-style patterns, replaces default ignore list
    --ignore-file <path>       file with gitignore-style patterns, replaces default ignore list
    --no-merge-gitignore       don't merge a CWD .gitignore into the active ignore list
    --no-line-numbers          do not prefix each line with its line number
    --max-size <mb>            skip files larger than this size in MB
    --max-lines <n>            skip files with more lines than this
-h, --help                     display help
-V, --version                  output the version number