HTPD

Turn long PDFs into documents AI reads correctly - exact text, every answer with its page.

In plain words  ·  See it work  ·  Install  ·  Use with your AI  ·  For developers  ·  Quality  

In plain words

You have a long PDF - a 300-page datasheet, a 5000-page reference manual, a policy, a report - and a question about it. Given the whole PDF, an AI often answers slowly, misses details, mixes up tables and cannot show where its answer comes from.

HTPD prepares the document for the AI. The converter turns the PDF into one .htpd file: the same text, word for word, cut into the document's own chapters and sections, with the page of every paragraph, the tables as rows, and the figures as pictures. The AI then reads only the few sections a question needs and answers from the exact text - with the page, so you can check it.

Try it in the browser: HTPD Studio.

See it work

Real commands and their output on a public 109-page data sheet (NXP i.MX 93, shortened where long).

1. Convert the PDF once - about a second for 100 pages:

2. Ask in your own words - the exact line from the document, with its page and section:

3. Figures stay pictures - an AI that can see images looks at the diagram itself:

In daily use you do not type these commands: you give the .htpd file to your AI, or let the plugin, the skill or the MCP server do it for you.

Install in one minute

The converter and the reader run on your computer. What reaches an AI is only the text you give it.

Use it with your AI

/plugin marketplace add narendrachampaneri/htpd
/plugin install htpd@htpd

pip install htpd-reader                                   # htpd-read and htpd-mcp, nothing else needed
claude mcp add htpd -- htpd-mcp --bundles ~/manuals       # Claude Code

For developers

How it works

flowchart LR
    PDF["📄 PDF<br/>scanned or digital"] -->|htpd convert| H["HTPD<br/>sections · pages · tables · figures"]
    H -->|upload| CHAT["AI chat<br/>(file + reading rules)"]
    H -->|skill · plugin · MCP| AGENT["AI agent<br/>(Claude, Antigravity, Codex)"]
    CHAT --> ANS["Answer from the exact text<br/>with page numbers"]
    AGENT --> ANS

Quick start

Download (no build needed) from the release page:

tar xzf htpd-0.1.2-linux-x64.tar.gz
cd htpd-0.1.2-linux-x64
./htpd convert manual.pdf --single           # writes manual.htpd
sudo apt install tesseract-ocr               # optional: read scanned pages too

Build from source - Linux (Ubuntu 24.04, also WSL), g++ 13+, make or CMake, Python 3.10+:

git clone https://github.com/narendrachampaneri/htpd.git && cd htpd
./scripts/get_pdfium.sh        # the PDF engine, once (about 4 MB)
make                           # builds build/htpd
make test                      # the C++ tests

Convert and ask:

./build/htpd convert manual.pdf --single     # one file: manual.htpd  (for AI chats)
./build/htpd convert manual.pdf              # a folder: manual.htpd/ (for tools and agents)

pip install htpd-reader                      # or: python3 -m pip install -e .
htpd-read ask examples/single-file/sample.htpd "What is the maximum bus voltage?"

[page 2, 2.1.1 Limits]
  Parameter | Min | Typ | Max | Unit
  Bus voltage | 200 | 400 | 480 | V

Every answer line is copied word for word from the file; --context adds the whole sections for the AI. More commands: contents, section, search, figure, check - see reader/README.md.

The format

An HTPD document is plain UTF-8 text: Markdown with a few fields. Any model, editor or grep can read it.

<!-- htpd section {"n":14,"id":"sections/0014-4-1-5-maximum-frequency-of-main-modules","number":"4.1.5","level":3,"pages":[18,18,18],"parent":"sections/0008-4-1-chip-level-conditions"} -->
## [S14] 4.1.5 Maximum frequency of main modules

Path: 4 Electrical characteristics > 4.1 Chip-level conditions > 4.1.5 Maximum frequency of main modules - page 18

<!-- page 18 -->

```text
Cortex®-A55 cores | 0.9 GHz | 1.4 GHz | 1.7 GHz
DRAM | 933 MHz | 1400 MHz | 1866 MHz
NPU | 500 MHz | 800 MHz | 1000 MHz
```

• Sections follow the document's own headings and form a tree: parent, children, previous, next.
• Page marks <!-- page N --> stand above the text of every page.
• Tables are rows with | between cells; code and listings keep their spacing.
• Figures are PNG pictures with caption and page, stored inside the file.
• Two forms, same content: a single .htpd file (for chats) and a folder with one file per section (for tools), which is also a valid Open Knowledge Format bundle.

The full specification is docs/FORMAT.md. Examples: examples/single-file/sample.htpd and examples/sample.htpd/.

Quality

Speed and size - single file, figures and OCR on, a 2-core cloud machine:

Most of a file with figures is their pictures, at its very end; the text comes first. --figures off leaves them out.

Finding the answer - 133 test questions about two public manuals (eval/report.md, written by the evaluation harness):

The text handed to the AI is about 6 % of the whole document, and the reader correctly says "not in this file" for 95 % of the questions the manuals do not answer.

Many kinds of PDF - 45 PDFs of known text, made by Word, LaTeX, Chrome, wkhtmltopdf and slide software, scanned, and with letters drawn as shapes (tests/zoo): 99 % of the text in order, 96 % of the headings, 89 % of the table rows exact.

Robustness - a stress test of 34 difficult PDFs (two columns, sideways tables, rotated pages, 1500 pages, encrypted, truncated and corrupted files): no crash, no hang, every file valid, no word lost. 102 C++ tests and 155 Python tests run on every change.

Project layout

include/ src/ cli/      the converter (C++23, PDFium is used in one file only)
reader/htpd_reader/     the reader: bundle, check, search, retriever, re-ranker, packer, answer, MCP server
skills/htpd/            the skill for AI apps (scripts/build_skill.py packs it)
skills/convert/         the plugin's skill that converts PDFs
.claude-plugin/         the Claude Code plugin and its marketplace (this repository is both)
eval/                   evaluation harness, baselines, report
model/                  the training of the re-ranker
tests/                  C++ tests, test PDFs, the stress test, the document zoo
docs/                   FORMAT.md · CONVERTER.md · READER.md · AI-APPS.md · BACKGROUND.md
examples/               a converted document in both forms

Contributing

Issues and pull requests are welcome. Before you change anything, read AGENTS.md; the short version:

• All tests pass before a change is merged: make test and python3 -m pytest.
• Every new rule in the code comes with a test that fails without it.
• Never lose text and never make text up.
• A change to what is written into an HTPD file updates docs/FORMAT.md in the same commit.

License

HTPD is open source under the Apache License 2.0: you may use, change and share it, also in commercial products, as long as you keep the copyright and license notices (NOTICE) and mark what you changed. The license includes a patent grant from every contributor.

PDFium, which the converter uses, is not part of this repository and has its own license (BSD-style with an Apache-2.0 part); after scripts/get_pdfium.sh its license texts are in third_party/pdfium/licenses/. If you give the program to others together with libpdfium.so, give them those files too.