gs-batch PDF Processing

Expert guidance for working with the `gs-batch-pdf` repository, a CLI tool for batch processing PDF files using Ghostscript with multi-threaded support.

Project Overview

`gs-batch-pdf` is a Python CLI tool that provides batch PDF processing capabilities including compression, PDF/A conversion, and custom Ghostscript operations. It uses `uv` for dependency management, Click for CLI framework, and supports parallel processing.

Key Architecture

Core Components

Features

Development Commands

Environment Setup

```bash

uv sync # Install dependencies

uv sync --dev # Install with dev dependencies

```

Testing

```bash

uv run pytest # Run all tests

uv run pytest tests/test_gsb.py # Run specific test

uv run pytest -v # Verbose output

```

Local Development

```bash

uv run python -m gs_batch.gs_batch --help # Test CLI locally

uv run gs_batch --help # Test installed command

```

Building & Distribution

```bash

uv build # Create distributions

uv publish # Publish to PyPI

```

Session Startup Protocol

**CRITICAL**: At the start of EVERY session, always:

1. **Check `_todo/todo.md`** for new or updated tasks from the user

2. **Check `_todo/proposal/`** for user-reviewed proposals ready to approve/implement

3. **Check `_todo/pending/`** for active tasks requiring progress updates

4. **Check git status** and recent commits for context

Task Planning System

The project uses a structured planning workflow in `_todo/`:

Directory Structure

```

_todo/

├── todo.md # Master task list (user-maintained)

├── proposal/ # Initial proposals awaiting approval

├── pending/ # Active development tasks

└── completed/ # Archive organized by completion date

└── YYYY-MM-DD/

```

Workflow Phases

#### 1. Proposal Phase

When user creates a task in `_todo/todo.md`:

#### 2. Development Phase

After user approval:

#### 3. Completion Phase

After task completion:

Development Best Practices

Error Handling

File Operations

Testing

Dependencies

**Runtime**: click, tqdm, show-in-file-manager

**Development**: pytest, ipykernel

**External**: Ghostscript (required system dependency)

Important Notes