DocMax
Terminal-native document engineering toolkit.
Local-first · Dual-engine · Atomic safety · AI-agent ready via MCP
Overview
DocMax is a high-performance, terminal-native document toolkit for developers, power users, and AI assistants. Merge, split, OCR, compress, convert, protect, sanitize, watermarking, and reorder PDFs and images — locally, privately, with no background servers or browser dependencies required.
# Install the core CLI
pip install Docmax
# Combine PDFs with source bookmarks
docmax merge report_q1.pdf report_q2.pdf -o annual_report.pdf
# OCR a scanned PDF with auto-deskewing
docmax ocr scan.pdf -o searchable.pdf --lang eng+fra
# Compress a heavy PDF using Ghostscript presets
docmax compress document.pdf -o compressed.pdf --preset ebook
# Connect directly to your AI assistant (Claude Desktop, Cursor, Claude Code)
docmax mcp connect
Why DocMax?
Most document tools require running heavy web services (Docker containers, local HTTP servers, browser tabs) or rely on fragile, non-atomic shell scripts that can corrupt documents on interruption.
DocMax takes a terminal-native, architecture-first approach:
| Feature | DocMax | Traditional Web Tools | Ad-Hoc Scripts |
|---|---|---|---|
| Installation | Single pip install |
Docker + container orchestration | Fragmented CLI tools |
| Interface | CLI, Full-Screen TUI & MCP | Web browser UI | Terminal only |
| Scripting & CI/CD | Native argv + --json |
REST API against running daemon | Shell scripts |
| Over SSH / Headless | First-class native support | Requires SSH port forwarding | Works |
| AI Assistant (MCP) | Built-in stdio & HTTP bridge | Unsupported / Custom bridge | Custom wrappers |
| Integrity Guarantees | Atomic staging & validation | Varies by service | Vulnerable to partial writes |
| Document Privacy | 100% Local by default | Local server | Local machine |
Architectural Guarantees & Safety
DocMax was built from the ground up to prevent destructive file operations and silent data loss. Every guarantee is enforced through automated tests across Linux, macOS, and Windows:
- Atomic File Swaps: All outputs are written to temporary staging files, verified, and only then atomically swapped into place via
core/atomic.py. If a process is interrupted or fails midway, your target file remains intact or absent — never half-written. - In-Place Overwrite Prevention: Input files can never be used as the output destination (
docmax merge a.pdf b.pdf -o a.pdfis refused before processing begins). - Accidental Overwrite Protection: Overwriting an existing destination strictly requires the
--forceflag. - Zero Raw Tracebacks: Known errors produce human-actionable messages with clear remedy hints (or structured JSON objects in automated pipelines).
- Predictable Cleanups: Intermediate files from pipelines, OCR rasterizations, and image conversions live in isolated temporary directories that are automatically purged on success, cancellation, or error.
Core Capabilities
1. Dual-Engine Architecture (Local vs. Cloud)
Every tool can run two ways, with your privacy always in your control:
- Local Engine (Default): Runs 100% offline on your machine using local binaries and Python libraries.
- Cloud Engine (Optional): Offloads compute-heavy operations (
compress,convert,ocr) to an external or self-hosted Cloud Engine server without requiring heavy local system dependencies.
docmax ocr scan.pdf # Automatically selects available engine
docmax ocr scan.pdf --engine local # Forces local offline processing
docmax ocr scan.pdf --engine cloud # Offloads processing to cloud engine
Privacy Contract: Nothing is ever transmitted to the cloud without explicit consent. Consents are granted per-tool via
docmax cloud agree, recorded locally, and can be revoked at any time. Settingoffline = truein your configuration permanently disables all outbound network traffic regardless of flags.
2. Four Unified Interfaces
DocMax provides four consistent entry points into the exact same registry and engine router:
- UNIX CLI: Standard UNIX semantics, flag-driven execution, and a global
--jsonmode for scripting. - Interactive TUI: Full-terminal dashboard powered by Textual (
docmax tuior simply typingdocmaxin an interactive shell). - Visual Pickers: Interactive browser-assisted helpers (
--interactive) for visual tasks like bounding-box selection (docmax crop) and page sequencing (docmax reorder). They compute coordinates and return them to the CLI without touching the original document. - Model Context Protocol (MCP): Connects your tools directly to LLM agents (Claude Desktop, Cursor, Claude Code, Cline) via stdio or streamable HTTP.
Complete Tool Suite
DocMax provides over 20+ purpose-built tools across document and image workflows:
PDF Assembly & Page Operations
| Command | Description | Engine |
|---|---|---|
docmax merge |
Combine multiple PDFs in specified order with bookmarks/outline preservation | Local |
docmax split |
Split PDF into individual pages or specific range-based output files | Local |
docmax rotate |
Rotate entire document or specified pages by 90°, 180°, or 270° | Local |
docmax pages |
Extract or drop specific pages and ranges (1-3,5,7-end) |
Local |
docmax reorder |
Rearrange page sequences manually or via visual drag-and-drop (--interactive) |
Local |
docmax crop |
Trim page margins to explicit point coordinates or visual box (--interactive) |
Local |
Security, Sanitation & Inspection
| Command | Description | Engine |
|---|---|---|
docmax protect |
Encrypt PDF with AES-256 / AES-128 and granular access permissions | Local |
docmax unlock |
Remove encryption from password-protected documents | Local |
docmax permissions |
Inspect active PDF encryption flags, permissions, and security restrictions | Local |
docmax sanitize |
Scrub metadata, hidden annotations, JavaScript, forms, and embedded files | Local |
docmax metadata |
Read or update document title, author, subject, keywords, and producer | Local |
docmax get-info |
Fast document summary (page count, dimensions, PDF version, encryption) | Local |
Document Enhancement & Conversion
| Command | Description | Engine |
|---|---|---|
docmax ocr |
Generate searchable PDFs with Tesseract OCR, auto-deskew, and language selection | Local / Cloud |
docmax compress |
Optimize and downsample PDFs via Ghostscript presets (screen, ebook, printer) |
Local / Cloud |
docmax watermark |
Apply custom text watermarks with opacity, rotation, and 9 alignment anchors | Local |
docmax stamp |
Overlay a page from another PDF as a stamp or official letterhead | Local |
docmax convert |
Convert documents between Markdown, HTML, Word, ODT, LaTeX, EPUB, and TXT | Local / Cloud |
docmax to-images |
Rasterize PDF pages to high-resolution PNG, JPEG, or TIFF images | Local |
docmax from-images |
Assemble raster images into a single PDF (lossless JPEG passthrough) | Local |
Image Processing
| Command | Description | Engine |
|---|---|---|
docmax compress-image |
Lossy and lossless image compression (JPEG, PNG, WebP) | Local |
docmax convert-image |
Transcode between modern image formats (PNG, JPEG, WebP, TIFF, BMP) | Local |
docmax resize |
Scale images by dimensions, scale factor, or aspect-fit bounds | Local |
docmax remove-bg |
AI-powered automatic background removal via rembg |
Local |
docmax watermark-image |
Overlay text or watermark stamps onto image assets | Local |
Installation & Setup
Package Extras
DocMax maintains an ultra-lightweight base installation. Advanced dependencies are isolated into modular extras:
# Core installation (pure Python, fast install)
pip install Docmax
# Add specific capabilities
pip install "Docmax[ocr]" # OCR image pre-processing & deskewing
pip install "Docmax[tui]" # Interactive Textual dashboard
pip install "Docmax[crypto]" # AES-256 PDF encryption/decryption
pip install "Docmax[mcp]" # Model Context Protocol server for AI assistants
pip install "Docmax[images]" # Advanced image rasterization and assembly
pip install "Docmax[tables]" # Table extraction from PDFs
pip install "Docmax[remove-bg]" # AI-powered background removal
# Install all features
pip install "Docmax[all]"
External Binaries
Certain local engines rely on battle-tested system binaries:
- Ghostscript (
gs): Used bycompress - Tesseract (
tesseract): Used byocr - Poppler (
pdftoppm): Used byto-imagesandocr - Pandoc (
pandoc): Used byconvert
DocMax makes checking and installing these effortless:
# Inspect system dependency status
docmax doctor
# Automatically install missing binaries for your platform (brew / apt / winget)
docmax setup
Power Workflows: Pipelines, Batch & Watch
Compose and automate operations across documents without writing glue code:
1. Multi-Stage Pipelines (docmax pipeline)
Chain multiple tools into a single, cohesive operation defined in a simple TOML configuration:
# clean_scan.toml
name = "clean-scan"
[[stage]]
tool = "ocr"
params = { lang = "eng", dpi = 300 }
[[stage]]
tool = "compress"
params = { preset = "ebook" }
[[stage]]
tool = "watermark"
params = { text = "CONFIDENTIAL", opacity = 0.2, position = "center" }
Run the pipeline:
docmax pipeline unverified_scan.pdf --pipeline clean_scan.toml -o final_document.pdf
Guaranteed safety: Intermediate stages write only to an isolated temporary sandbox. If stage three fails, intermediate files are cleanly discarded and your destination remains untouched.
2. Resilient Batch Processing (docmax batch)
Process hundreds of files in bulk with independent error handling:
docmax batch incoming/*.pdf --output-dir processed/ --tool ocr
Resilient execution: If file 14 is corrupted, it is logged with a structured error while the remaining 199 files proceed to completion.
3. Directory Watcher (docmax watch)
Monitor drop directories and automatically process arriving files:
docmax watch ~/Downloads/Scans --output-dir ~/Documents/Archive --tool ocr
Loop and race protection: Incoming files are processed only after their byte size has settled across polling intervals, and output directories cannot overlap watched directories.
AI Agent Integration (MCP)
DocMax turns your local document tools into an extensible tool suite for AI assistants via the Model Context Protocol (MCP).
Auto-Configuration
Connect DocMax to your local AI applications with a single command:
docmax mcp connect
This automatically detects and safely updates configurations for Claude Desktop, Claude Code, and Cursor, inserting the server definition:
{
"mcpServers": {
"docmax": {
"command": "docmax",
"args": ["mcp", "--root", "/path/to/documents"]
}
}
}
Security & Agent Sandboxing
When driven by an AI agent, DocMax enforces strict security perimeters:
- Directory Confinement (
--root): The agent cannot read or write outside designated directories. Path traversal (..) and symlink escapes are strictly rejected. - Destructive Overwrites Forbidden: Overwrite flags (
--force) are disabled for agent invocations. Existing destinations return structured errors. - No Unsolicited Cloud Uploads: Cloud execution is disabled by default. An agent cannot grant consent on your behalf.
- Cancellation Propagation: Interrupting a running agent request triggers immediate cancellation of the underlying worker thread, leaving files undamaged.
Scripting & Automation (--json)
Every DocMax command supports global machine-readable output:
docmax get-info sample.pdf --json
Output:
{
"ok": true,
"data": {
"pages": 12,
"title": "Quarterly Report",
"encrypted": false,
"pdf_version": "1.7",
"file_size": 245120
}
}
Diagnostics and progress bars are routed exclusively to stderr, leaving stdout clean for programmatic consumption.
Developer Guide & Architecture
DocMax is structured with a strict, lint-enforced layered architecture (ADR 0035):
CLI Interface (docmax.cli) TUI Interface (docmax.tui)
\ /
v v
Engine Router (docmax.core.router) <--> Tool Registry (docmax.core.registry)
/ \
v v
Local Tools (docmax.tools.*) Shared Schemas (docmax.mcpschema)
| |
v v
Atomic Writers & Protocols Model Context Protocol (docmax.mcp)
Contributing & Development
# Clone repository
git clone https://github.com/megabyte44/docmax.git
cd docmax
# Set up virtual environment and development dependencies
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
# Run test suite & linters
pytest
ruff check .
mypy
lint-imports
Explore our architectural documentation:
- Architecture Overview — Structural design and constraints
- Architectural Decision Records (ADRs) — The rationale behind every core decision
- Implementation Guides — Deep dives into core, runner, and MCP subsystems
License
This project is licensed under the MIT License. See the LICENSE file for details.
Metadata
Release files for Docmax 3.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| docmax-3.3.3.tar.gz | 297.6 kB | With provenance | Details for docmax-3.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| docmax-3.3.3-py3-none-any.whl | Python 3 | none | any | Details for docmax-3.3.3-py3-none-any.whl |
Total release size: 688.0 kB
Release files / docmax-3.3.3.tar.gz
| Download URL | docmax-3.3.3.tar.gz |
|---|---|
| Size | 297.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a978f77327b4e93a2ee51fc3aeef6b103ccdb0c20fb1a374c628ce78969b46cf
|
|
BLAKE2b-256 checksum How to use checksums |
9d6c04b4884012f93b5b4532715402e8f8760438a4bdcc61958a1282699ac081
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / docmax-3.3.3-py3-none-any.whl
| Download URL | docmax-3.3.3-py3-none-any.whl |
|---|---|
| Size | 390.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28db2e2056fb1359341ca75622e77ee82df8359cf79d82d0d885ad863b7a992a
|
|
BLAKE2b-256 checksum How to use checksums |
572be4905a47ad9081a35ed43754ececd8a05232bf440ece3866f466c2560002
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logSecurity for Docmax 3.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for docmax-3.3.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.