Snapshot your codebase into compact JSON/JSONL — perfect for LLMs.
Single file. Zero dependencies. No install.

---

paleae is a single-file, zero-dependency utility that scans your repository and creates a structured snapshot optimized for AI analysis. It's designed to be simple, transparent, and trustworthy.

Key Features

• Single File, Zero Deps: Drop paleae.py into any project. It runs anywhere Python runs, with no pip install required.
• Local-First: Scans files on your machine. No code is ever sent over the network.
• AI-Ready Output: Generates clean JSON or JSONL designed for machine consumption. The structured format is perfect for populating LLM context windows, building Retrieval-Augmented Generation (RAG) systems, or creating training datasets.
• Configurable: Use powerful include/exclude regex patterns and a .paleaeignore file (with ! negation) to precisely control what gets included.
• Rigorously Tested: 100% line and branch coverage, fully type-checked with MyPy, linted with Ruff, and hardened with Hypothesis property-based tests and pydocstyle compliance.

Quick Start

No installation needed. Just download and run.

# Download the script
curl -fsSL https://raw.githubusercontent.com/PaulTiffany/paleae/main/paleae.py -o paleae.py

# Snapshot the current directory
python paleae.py

This will create a repo_snapshot.json file in your current directory.

Usage with AI Assistants

If you are using an AI assistant, it can leverage paleae to help you more effectively. Your assistant can:

1. Suggest snapshot commands tailored to your project to get the best context for analysis.
2. Generate custom .paleaeignore files to exclude noise and focus on the most relevant code.

See the project Cookbook for detailed recipes and examples.

Contributing

We welcome contributions! If you're interested in helping improve Paleae, please read our comprehensive Contributing Guide for details on setting up your development environment, running tests, and submitting pull requests.

Privacy & Safety (30s)

• Runs locally in read-only mode. No execution. No network.
• Skips binaries, huge files (>10 MB), VCS/caches, and .env by default.
• Add a .paleaeignore to exclude anything sensitive.
• You are responsible for what you share—review the JSON before uploading.

Usage

usage: paleae [-h] [-o OUT] [-f {json,jsonl}] [--profile {minimal,ai_optimized}]
              [--include INCLUDE] [--exclude EXCLUDE] [--version] [--about]
              [directory]

Create JSON/JSONL snapshot of your repo for LLMs

positional arguments:
  directory             Directory to snapshot (default: .)

options:
  -h, --help            show this help message and exit
  -o, --out OUT         Output file (auto-named if not specified)
  -f, --format {json,jsonl}
                        Output format
  --profile {minimal,ai_optimized}
                        File inclusion profile
  --include INCLUDE     Extra include regex (repeatable)
  --exclude EXCLUDE     Extra exclude regex (repeatable)
  --version             show program's version number and exit
  --about               Show project info and exit

Examples

Snapshot to a specific JSONL file:

python paleae.py -f jsonl -o my_project.jsonl

Use the ai_optimized profile to include only core source and config files:

python paleae.py --profile ai_optimized

Add a specific directory to the snapshot using a regex:

python paleae.py --include "^(docs|examples)/"

Configuration (.paleaeignore)

Create a .paleaeignore file in your project's root directory to exclude files and directories. The syntax is similar to .gitignore.

# .paleaeignore

# Ignore build artifacts and logs
build/
dist/
*.log

# But force-include an important log file
!important.log

Output Format

The snapshot contains metadata and a list of file objects.

{
  "meta": {
    "tool": "paleae",
    "version": "1.0.0",
    "timestamp": "2025-09-16T20:00:00Z",
    "root_directory": "/path/to/your/project",
    "summary": {
      "total_files": 42,
      "total_chars": 123456,
      "estimated_tokens": 30864
    }
  },
  "files": [
    {
      "path": "src/main.py",
      "content": "print('hello')",
      "size_chars": 14,
      "sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
      "estimated_tokens": 3
    }
  ]
}

License

This project is licensed under the MIT License.

The brand assets (assets/*.svg) are dedicated to the public domain under CC0 1.0 Universal. E.txt).