<h1 align="center">PDFCompress</h1>

<p align="center">Structure-preserving PDF compression for humans and AI agents — keep text and vectors intact, downsample only oversized images, and verify every result.</p>

<p align="center">
  <a href="https://openai.com/codex"><img alt="Codex Code Support" src="https://img.shields.io/badge/Codex-Code_Support-000000?logo=openai&logoColor=white"></a>
  <a href="https://openai.com"><img alt="GPT-5.6-Sol Agent" src="https://img.shields.io/badge/GPT--5.6--Sol-Agent_used%400.1.0-10A37F"></a>
  <a href="https://github.com/ncepuee/PDFCompress"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ncepuee/PDFCompress?logo=github&cacheSeconds=86400"></a>
</p>

<p align="center">
  <a href="https://github.com/ncepuee/PDFCompress/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/ncepuee/PDFCompress?display_name=tag&sort=semver"></a>
  <a href="https://github.com/ncepuee/PDFCompress/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ncepuee/PDFCompress/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/Python-%E2%89%A53.11-3776AB?logo=python&logoColor=white"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/ncepuee/PDFCompress"></a>
</p>

PDFCompress is an open-source, structure-preserving PDF compressor for humans and AI agents. It
uses independently verified WPS-style image presets, but does **not** call or distribute WPS DLLs
and does not depend on a WPS account.

Its core rule is simple:

> Keep text and vectors as text and vectors; downsample only oversized painted images; verify the
> result before publishing it.

## Features

- Computes image resolution from the actual PDF transformation matrix, including images nested in
  Form XObjects.
- Applies WPS-compatible `high`, `standard`, `medium`, and `low` settings.
- Adds an `archive-safe` profile for award, tender and archival attachments.
- Preserves the source file and writes atomically to a different output path.
- Preserves bookmarks, attachments, annotations, fonts and visible PDF structure by default.
- Refuses signed PDFs unless signature invalidation is explicitly accepted.
- Verifies page count, page boxes and extractable text after every candidate.
- Supports a target size without repeatedly recompressing the previous JPEG result.
- Provides a Python API, CLI, shared Agent Skill, Codex plugin, Claude Code plugin, and MCP server.

## Installation

Python 3.11 or newer is required.

```powershell
git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"
```

With `uv`:

```powershell
uv tool install --editable ".[mcp]"
```

Install the tagged GitHub release without cloning:

```powershell
uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"
```

## Quick start

Analyze before compressing:

```powershell
pdfcompress analyze "input.pdf" --json
```

Compress using the WPS-compatible high-quality profile:

```powershell
pdfcompress compress "input.pdf" "output.pdf" --preset high --json
```

For a formal attachment that must be under 4 MB:

```powershell
pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json
```

Verify an existing pair:

```powershell
pdfcompress verify "input.pdf" "output.pdf" --json
```

## Presets

| Preset | Trigger PPI | Target PPI | JPEG quality | Intended use |
| --- | ---: | ---: | ---: | --- |
| `archive-safe` | 360 | 300 | 85 | Conservative formal and archival attachments |
| `high` | 300 | 300 | 75 | WPS-compatible high quality |
| `standard` | 150 | 150 | 75 | WPS-compatible standard quality |
| `medium` | 110 | 110 | 50 | WPS-compatible medium quality |
| `low` | 96 | 96 | 30 | WPS-compatible low quality |

The four WPS-compatible values were recovered from the installed compression plugin's
`generateCompressArgs` branches and independently documented in the companion analysis note. The
exact WPS resampling kernel, chroma subsampling policy and complete optimizer bitmask are not copied
or claimed.

## Target-size behavior

When `--target-size-mb` is supplied, PDFCompress tries progressively stronger profiles starting at
the requested preset. Every attempt reopens the original PDF:

```text
archive-safe → high → standard → medium → low
```

The first verified candidate under the limit is selected. If no profile reaches the limit, the
smallest verified candidate is returned with a warning. PDFCompress does not silently rasterize
pages, delete fonts, or remove attachments to force the target.

## Agent integration

### Claude Code

Install the Python package first, then load the plugin for a session:

```powershell
cd PDFCompress
claude --plugin-dir .
```

Invoke the skill as `/pdfcompress:pdf-compress`, or ask Claude to compress a PDF. Claude Code also
loads the plugin's `.mcp.json` and starts `pdfcompress-mcp` over stdio.

### Codex

The repository contains a validated `.codex-plugin/plugin.json`, a shared `skills/` directory and
`.mcp.json`. It can be installed from a local Codex marketplace, or the skill can be copied to a
personal/project skill directory. The core package must be installed so `pdfcompress-mcp` is on
`PATH`.

### Generic MCP clients

Use this stdio configuration:

```json
{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}
```

MCP tools:

- `analyze_pdf(path, password?)`
- `compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)`
- `verify_pdf(input_path, output_path)`

## Open-source research and adopted ideas

| Project | Strength | What PDFCompress adopts |
| --- | --- | --- |
| [qpdf](https://github.com/qpdf/qpdf) | Mature content-preserving PDF transformations and repair | Reliable parsing, object-stream writing and structural preservation through pikepdf |
| [pikepdf](https://github.com/pikepdf/pikepdf) | Python API over qpdf | Core object model, image decoding, resource cleanup and save pipeline |
| [pdfcpu](https://github.com/pdfcpu/pdfcpu) | Standalone batch CLI and broad validation commands | Script-friendly subcommands and JSON reports |
| [OCRmyPDF](https://github.com/ocrmypdf/OCRmyPDF) | Safe staged processing and PDF/A-aware workflows | Temporary candidates, final verification and atomic publishing |
| [Ghostscript](https://github.com/ArtifexSoftware/ghostpdl) | Effective image downsampling controls | Separate trigger PPI, target PPI and quality presets; not bundled because of license boundary |
| [MuPDF](https://github.com/ArtifexSoftware/mupdf) | Multi-level garbage collection and duplicate stream reuse | Aggressive cleanup is treated as a separate, testable stage; not bundled |
| [pdfsizeopt](https://github.com/pts/pdfsizeopt) | Multi-stage smallest-file optimization | Compare candidates and select the smallest verified output |

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for license boundaries.

## Safety and limitations

- Rewriting a PDF invalidates digital signatures. The default is to stop.
- Encrypted PDFs require a password; encryption is preserved on output.
- Version 0.1 skips image masks, transparency, custom decode arrays, unusual color spaces and
  non-8-bit images instead of risking visual corruption.
- Text equality checks use extractable text. Scanned pages without OCR still require visual QA.
- Pixel-level render comparison is recommended before using the tool on legally significant or
  highly complex documents.
- If a candidate is not smaller than the source, PDFCompress outputs a byte-for-byte source copy
  and reports that no safe size reduction was found.

## Validated example

On a 12-page, image-heavy PDF used during development:

| Profile | Source | Output | Reduction | Verification |
| --- | ---: | ---: | ---: | --- |
| `archive-safe` | 24,004,483 B | 3,149,368 B | 86.88% | Pages, boxes and extracted text equal |
| `high` | 24,004,483 B | 2,940,952 B | 87.75% | Pages, boxes and extracted text equal |

At 100 DPI render comparison, all page dimensions matched; the `archive-safe` result had a mean
per-page RGB RMS difference of 0.388 and a maximum of 3.002 on a 0–255 channel scale. This is one
validation case, not a universal quality guarantee.

## Development

This repository is developed with Codex as the coding agent; the current release cycle was
implemented and verified with the GPT-5.6-Sol agent model.

```powershell
python -m pip install -e ".[mcp,dev]"
pytest
ruff check .
```

Tests generate their own PDF containing searchable text and a high-resolution image. No private
documents are included in the repository.

## License

PDFCompress is released under the [MIT License](LICENSE). Third-party dependencies retain their own
licenses.

See the [changelog](CHANGELOG.md) and [GitHub releases](https://github.com/ncepuee/PDFCompress/releases)
for versioned changes and downloadable Python packages.