📦 ai-pack

Pack your entire codebase, specific files, or uncommitted changes into a single token-optimized Markdown prompt for LLMs (like ChatGPT, Claude, Gemini).

⚡ Key Features

• 📋 Clipboard-First: Automatically copies your prompt, ready to paste straight into ChatGPT, Claude, Gemini, or any LLM interface.
• 💀 Skeleton Mode (-s / --skeleton): Drastically saves tokens by stripping function/method bodies, keeping only class structures, signatures, and imports.
• 🎯 Interactive Selector (-i): Choose files interactively via checkbox CLI menu.
• 🌿 Git-Aware (-c / --changed): Automatically pack only modified, staged, or untracked files.
• 🛡️ Gitignore-Respecting: Excludes ignored, temporary, or build files automatically (using git ls-files with manual fallback for non-git folders).
• 💬 Prompt Presets (-p): Instantly prepend pre-configured prompts for code review, bug hunting, or architecture explanations.
• 📊 Token Estimation: Heuristic token counting warns you if your payload exceeds your limit (--max-tokens).

🚀 Quick Start

Installation

Choose your preferred installation method:

# Option 1: Install official package via pip (Recommended)
pip3 install ai-pack-cli --user

# Option 2: Install via pipx (Isolated environment)
pipx install ai-pack-cli

# Option 3: Standalone Executable (Zero dependencies - No Python required!)
# Linux:
curl -sSL https://github.com/iamraydoan/ai-pack/releases/latest/download/ai-pack-linux-x86_64 -o /usr/local/bin/aip && chmod +x /usr/local/bin/aip

# macOS:
curl -sSL https://github.com/iamraydoan/ai-pack/releases/latest/download/ai-pack-macos-arm64 -o /usr/local/bin/aip && chmod +x /usr/local/bin/aip

# Windows: Download ai-pack-windows-x86_64.exe from GitHub Releases

💡 Usage & Common Scenarios

Here are common ways to use ai-pack (using commands aip, ai-pack, or aipack):

1. Pack codebase & copy to clipboard (Default)

aip

2. Pack specific files/folders and save to a file

aip -f src/main.py tests/ -o output.md

3. Pack only uncommitted changes with a code review prompt

aip -c -p review

4. Pack code skeleton to save context window tokens

aip -s -p explain

5. Choose files interactively before packing

aip -i

⚙️ CLI Flags & Interactions

Reference

🤝 Combining Flags

You can combine flags to narrow down and customize your payload:

• Filter Git changes (-f + -c / --changed): Only packs files that are both modified/uncommitted AND located inside the specified paths.

  aip -c -f src/
  

• Interactive selection with filter (-i + -f / -c): Shows only the filtered list (e.g. only changed files) in the interactive checkbox menu instead of the entire repo.

  aip -i -c
  

• Structure only (-s / --skeleton + any mode): Can be appended to any command to extract skeletons instead of full source code for the selected files.

  aip -i -s
  

• Redirect output (-o vs Default): By default, everything goes to the clipboard. Use -o filename.md to save to a file instead.

💀 Skeleton Mode Example

Original Code:

def fibonacci(n):
    if n <= 0:
        return []
    elif n == 1:
        return [0]
    sequence = [0, 1]
    while len(sequence) < n:
        sequence.append(sequence[-1] + sequence[-2])
    return sequence

Skeleton Output:

def fibonacci(n): ...

🤝 Contributing

Contributions are welcome! Please check out the Developer & Contributing Guide for local setup, running unit tests, and code formatting guidelines (ruff).

1. Fork the repository.
2. Create your feature branch (git checkout -b feat/amazing-feature).
3. Commit your changes (git commit -m 'feat: add amazing feature').
4. Push to the branch (git push origin feat/amazing-feature).
5. Open a Pull Request.

Give this repository a ⭐ if it helped you pack your code for LLMs!