PDF Compressor for AIMA Portal / Compressor PDF para Portal AIMA

Compress and merge PDF/JPEG documents for uploading to the AIMA residence permit renewal portal (portal-renovacoes.aima.gov.pt). Built for Portugal's autorização de residência (residence permit) renewal process.

Compressor e unificador de documentos PDF/JPEG para upload no portal de renovações AIMA. Ferramenta para o processo de renovação de autorização de residência em Portugal.

Features

• Single-file compression (compress.py) — compress individual PDFs/JPEGs with configurable quality, DPI, grayscale, and auto-fit to size targets
• Batch AIMA compression (compress_aima.py) — compress a folder of PDFs with per-document strategies and merge into a single file under a byte budget
• Visual comparison (compare.py) — compare 4 compression methods side by side
• Claude Code slash commands — /compress and /compress-AIMA for interactive use

Requirements

System Dependencies

Install on macOS with Homebrew:

brew install python@3.13 imagemagick poppler ghostscript pdfcpu

Tool	Purpose
Python 3.13	Runtime
ImageMagick (magick)	Image processing and PDF assembly
poppler (pdftocairo)	PDF-to-image rendering
Ghostscript (gs)	PDF optimization preserving vector text
pdfcpu	Lossless structural PDF optimization (used by compare.py)

Python Dependencies

pip install pypdf>=6.0

Setup

git clone <this-repo>
cd compressor
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

Compress a single file

source .venv/bin/activate
python compress.py document.pdf                      # Default compression
python compress.py -q 40 large.pdf                   # More aggressive
python compress.py -g -m 2 large.pdf                  # Grayscale, auto-fit to 2 MB
python compress.py -E gs -g document.pdf              # Ghostscript (preserves vector text)

Batch compress for AIMA portal

source .venv/bin/activate
python compress_aima.py ~/Documents/aima-docs --prefix doc --budget-bytes 2000000 --open

This will:

1. Find all doc*.pdf files in the source directory
2. Compress each individually (Ghostscript for digital, render for scanned)
3. Auto-fit to budget by re-compressing largest files if needed
4. Merge all into docf.pdf and open in Preview

Compare compression methods

source .venv/bin/activate
python compare.py -m 2 document.pdf

Using with Claude Code

Claude Code is Anthropic's CLI tool that lets you use Claude directly in your terminal. This project includes slash commands that make compression interactive — Claude analyzes your files, runs compression, shows results, and helps you adjust quality.

Installing Claude Code

1. Install Node.js (v18+):

   brew install node

2. Install Claude Code:

   npm install -g @anthropic-ai/claude-code

3. Authenticate — run claude and follow the prompts to log in with your Anthropic account. You need an active Anthropic API key or a Claude Pro/Max subscription.

4. Navigate to this project:

   cd compressor
   claude

Slash Commands

Once inside Claude Code in this project directory:

Command	Description
/compress <files> [flags]	Compress individual files interactively
/compress-AIMA <source_dir> [flags]	Batch-compress PDFs for AIMA portal upload

Examples

/compress scan.jpg -q 40
/compress document.pdf -E gs -g -m 2
/compress-AIMA ~/Documents/aima-docs --prefix doc --budget-bytes 2000000
/compress-AIMA ~/Documents/aima-docs --prefix inv --scanned "inv.3 " --open

Interactive workflow with /compress-AIMA

1. Run /compress-AIMA ~/Documents/aima-docs --prefix doc --budget-bytes 2000000
2. Claude compresses each document, shows a size table
3. If over budget, automatically re-compresses largest files
4. Opens the merged PDF for visual verification
5. You can ask Claude to increase quality on specific files — it will re-compress and re-merge while staying under budget

Claude Code Requirements

• Node.js v18+ (brew install node)
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Anthropic account — one of:
  • Claude Pro subscription ($20/month) or Claude Max ($100/month)
  • Anthropic API key with credits
• All system dependencies listed above must be installed

Uso em Português

Esta ferramenta comprime e unifica documentos PDF para upload no portal de renovações AIMA — o portal do governo português para renovação de autorização de residência.

Funcionalidades principais

• Comprimir ficheiro individual: python compress.py documento.pdf -g -m 2 — comprime para PDF em escala de cinza com máximo de 2 MB
• Comprimir lote para AIMA: python compress_aima.py ~/docs --prefix doc --budget-bytes 2000000 — comprime e unifica todos os PDFs num único ficheiro
• Motor Ghostscript: python compress.py -E gs documento.pdf — preserva texto vetorial, ideal para documentos digitais

Requisitos

brew install python@3.13 imagemagick poppler ghostscript pdfcpu