SlyCat (Slice & Concatenate)

SlyCat is a Python utility designed to streamline interactions with large language models (LLMs) when working with multi-file software projects. It bundles entire projects (or selected parts) into a single, structured Markdown document suitable for LLM input. Crucially, it can also slice Markdown documents (like those generated by SlyCat or an LLM adhering to the format) back into a usable directory structure.

Key Features

• Project Bundling (concat): Combine specified files and folders into a single Markdown file.
  • Preserves relative file paths in clear headers (### **\path/to/file.ext`**`).
  • Automatically applies appropriate Markdown code fences with language identifiers (e.g., ```python) based on file extensions.
  • Intelligently attempts to detect and skip binary files (images, executables, archives etc.).
• Project Reconstruction (slice): Parses Markdown files formatted like SlyCat's output and recreates the described directory structure and files locally. Ideal for applying LLM-generated code back to your project.
• Selective Processing: Use powerful include (-i) and exclude (-x) patterns (supporting * and ? wildcards) to precisely control which files and directories are processed during concatenation. Common defaults (like .git, venv, node_modules, __pycache__) are excluded automatically.
• AI Formatting Guidance: Optionally add (-p) a standard instruction prompt at the beginning of the concatenated file, guiding the LLM to maintain the specific header and code fence format needed for reliable slicing later.
• Cross-Platform Compatibility: Uses standard libraries and normalized paths for better operation across different operating systems.
• No External Dependencies: Relies only on Python's standard library.

Installation

1. Clone the Repository:

   git clone https://github.com/RchGrav/SlyCat.git
   cd SlyCat

   (Replace RchGrav/SlyCat if the repository path is different)

2. Make the Script Executable (Optional):

   chmod +x slycat.py

   (Alternatively, you can always run it using python slycat.py ...)

Usage

Concatenate (Bundle) Files and Folders

./slycat.py [options] output_file.md [path1] [path2] ...

Arguments:

• output_file.md: The name for the generated Markdown bundle.
• path1, path2, ...: One or more files or folders to include.

Options:

• -p, --add-prompt: Prepend the standard AI instruction prompt to the output file.
• -f, --force: Overwrite output_file.md if it already exists.
• -x PATTERN, --exclude PATTERN: Exclude files/folders matching the pattern. Can be used multiple times. (e.g., -x "*.log" -x "build/")
• -i PATTERN, --include PATTERN: Only include files/folders matching the pattern. If used, items not matching any include pattern are skipped. Can be used multiple times. (e.g., -i "*.py" -i "src/")

Examples:

1. Bundle an entire project folder:

   ./slycat.py my_project_bundle.md ./my_project

   (This will exclude default patterns like .git, venv etc.)

2. Bundle specific parts, exclude logs, and add the AI prompt:

   ./slycat.py -p app_bundle.md main.py ./src ./config -x "*.log"

3. Bundle only Python and Markdown files from a directory:

   ./slycat.py docs_and_scripts.md ./project -i "*.py" -i "*.md"

Slice (Unbundle) Files

./slycat.py -s output_folder input_file1.md [input_file2.md ...]

Arguments:

• -s: Specifies slice mode.
• output_folder: The directory where the file structure will be recreated. It will be created if it doesn't exist.
• input_file1.md, ...: One or more Markdown files (formatted like SlyCat's output) to slice.

How it works:

SlyCat looks for the ### **\path/to/file.ext`**headers and the subsequent ```language ... ``` code blocks within the input Markdown file(s). It then writes the content of each code block to the specifiedpath/to/file.extrelative to theoutput_folder`.

• It works best with files generated by slycat.py concat.
• It can also work with LLM output if the LLM has correctly followed the formatting (using the -p prompt during concatenation helps encourage this).
• The script will attempt to skip the standard AI instruction prompt if it finds it at the beginning of an input file.

Example:

# Recreate project structure from an LLM response file
./slycat.py -s ./recreated_project llm_output.md

Supported File Types (for Code Fences)

SlyCat automatically detects the language for Markdown code fences based on these extensions (defaulting to text otherwise):

.py: python, .js: javascript, .html: html, .css: css, .sh: bash, .java: java, .cpp: c++, .c: c, .json: json, .yml/.yaml: yaml, .xml: xml, .rb: ruby, .rs: rust, .go: go, .md: markdown, .txt: text, .ini/.cfg: ini (...and more can be added in the script's CODE_FENCE_LOOKUP)

Contributing

Contributions are welcome! Please fork the repository, make your changes, and submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.