A native GNOME desktop AI assistant overlay. Highlight confusing text in any PDF (or anywhere on screen), press a hotkey, and get clear, context-aware explanations — without ever leaving your document or opening a browser.
GNOME PDF Agent is a seamless, distraction-free reading companion built specifically for the Linux desktop environment.
When you are reading a dense academic paper, textbook, or technical documentation in a standard viewer (like GNOME Document Viewer / Evince), you can simply highlight any confusing sentence with your mouse. By clicking a button or using a hotkey, a native sidebar slides in, allowing you to ask questions about that specific text.
More importantly, it is context-aware. If you load your PDF into the app beforehand, it reads and remembers the entire document. When you ask a question, the assistant uses the surrounding context from your document to give you highly accurate, tailored answers instead of generic guesses.
Reading complex material often involves constant, frustrating context-switching:
- The Distraction Penalty: You hit an unfamiliar term, alt-tab to a web browser, search for the definition, and inevitably lose your train of thought (or get distracted by open tabs).
- Generic Answers: Standard chatbots don't know what you are reading. They give you broad definitions that might not apply to the specific context of your textbook or paper.
- Friction: Having to constantly copy text, switch windows, paste it into a prompt box, and manually explain what you are reading is tedious.
GNOME PDF Agent solves this by:
- Keeping the assistant right next to your reading material in a beautiful, native sidebar.
- Automatically grabbing what you highlight so you never have to copy and paste.
- Cross-referencing your questions against the specific PDF you are currently reading to provide perfectly tailored explanations.
The application workflow is designed to be invisible and frictionless.
- Ingestion: You load a PDF into the application. The system quietly reads the document, breaks it down into paragraphs, and stores a mathematical representation (vectors) of the text on your local hard drive.
- Selection: You read your document normally. When you highlight text, the application intercepts your operating system's "Primary Selection" buffer (the temporary memory that holds highlighted text).
- Retrieval: You ask a question. The system instantly searches through the mathematical representations of your PDF to find the 3 or 4 paragraphs most relevant to your highlighted text and question.
- Generation: The application packages your question, your highlighted text, and the relevant paragraphs from the PDF, and sends them to a powerful cloud AI brain.
- Streaming: The AI processes the context and streams the answer back to your sidebar, typing it out in real-time.
The project leverages a modern, cutting-edge technology stack to provide a smooth desktop experience combined with powerful AI:
- Python 3: The core logic driving the application.
- GTK4 & libadwaita (via PyGObject): The foundation of the user interface. GTK4 provides hardware-accelerated rendering, while libadwaita ensures the application perfectly matches the modern, rounded, and polished design language of the GNOME desktop environment.
- Wayland APIs: Deep operating system integration allows the app to read the Wayland Primary Selection buffer securely and instantly, enabling the "highlight-to-grab" functionality without needing clipboard managers.
- LangChain: An advanced framework used to orchestrate AI pipelines. It manages the flow of taking your question, retrieving the right data, and formatting the prompts that go to the AI.
- ChromaDB: A high-performance vector database running locally on your machine. It stores the "embeddings" (mathematical vectors) of your PDFs. When you ask a question, Chroma performs an ultra-fast semantic search to find paragraphs in your document that mean the same thing as your question, even if they don't use the exact same words.
- PyPDF & Recursive Text Splitters: Tools used to accurately extract raw text from PDF files and slice them into overlapping chunks so that context isn't lost at the edges of paragraphs.
- Asynchronous Networking (HTTPX): The app uses fully asynchronous network calls and Server-Sent Events (SSE) to talk to the cloud brain. This ensures that the desktop interface never freezes while waiting for the network, and allows answers to stream in word-by-word.
Since the heavy lifting (the AI processing backend) is securely hosted in the cloud, you only need to run the lightweight desktop client on your machine.
You need a Linux distribution running GNOME (like Fedora or Ubuntu) and Python 3 installed. You will also need the system packages for GTK4.
On Fedora, you can install the requirements with:
sudo dnf install python3-devel gcc python3-gobject gtk4 libadwaita gobject-introspection-
Clone the repository and enter the directory:
git clone https://github.com/jaiveer077/gnome-pdf-agent.git cd gnome-pdf-agent -
Create a virtual environment: We recommend creating a virtual environment that has access to your system's GTK packages.
python3 -m venv --system-site-packages .venv source .venv/bin/activate -
Install the Python dependencies:
pip install -r requirements.txt
-
Launch the app!
python3 main.py
- Open the app using the command above.
- Click Load PDF Database and select the PDF you are about to read. Wait a few moments for the indexing to complete.
- Open your PDF in any viewer (like Evince or your web browser).
- Highlight any confusing text with your mouse.
- In the assistant window, click Grab Highlighted Text.
- Type your question into the entry box (e.g., "Explain this concept like I'm 5" or "How does this relate to the previous chapter?") and click Ask AI.
- Watch the tailored answer stream directly into your sidebar!