Magpie

Ask questions about your own files. Get answers, with the sources cited.

Hit ⌥Space, ask something in plain English, and get an answer grounded in your actual
documents — receipts, contracts, course catalogs, meeting notes, scanned PDFs — with clickable
links to the files it used. Your files never leave your machine.

named after the bird that caches thousands of finds across scattered hiding places —
and remembers where every one of them is.

---

macOS (Apple silicon) and Windows 10/11. Linux isn't in this beta (why).

---

_{Real capture — 282 indexed documents, a real question, a real cited answer.
Higher quality: docs/assets/demo.mp4}

---

The Problem

Every desktop search tool works the same way: you type keywords, it matches filenames and maybe some content. That's fine when you remember the exact word. It falls apart the moment you ask a real question.

• "How much was that flight to Hartford last March?"
• "Which course teaches relativity?"
• "What's our club's policy on guest voting?"

Spotlight can find a file whose name contains "Hartford," but it can't read the receipt and tell you the total. It can list every course catalog PDF, but it can't scan their contents and return the one covering relativity. The information is on your machine. The search tool just doesn't understand it.

Magpie is the "chat with your documents" experience — but pointed at your own filesystem instead of a curated upload.

---

Why Magpie?

The short version: grep needs the exact word. Spotlight needs the filename. Magpie needs the idea.

---

What It Does

• Answers, not hit lists. Every answer names the files it relied on, as clickable paths you can open or reveal in the file manager.
• Reads what other tools skip. Text, PDF, DOCX, XLSX, CSV, code, Markdown — plus scanned pages and photos, through a visual model that embeds the rendered page instead of giving up on it.
• Two embeddings, because one isn't enough. A dense vector so "pay the landlord" finds "rent payment," and a sparse BM25 vector so PHY-312 and $143.50 stay findable literally. Both are fused at query time.
• Tables stay row-addressable. A 3-sentence summary indexes a receipt well; a 1,700-row course catalog is indexed per row, so individual courses stay findable.
• Incremental by default. A manifest tracks every file. Adding one file to a folder of thousands re-processes exactly one file.
• The filesystem stays the source of truth. Nothing is copied into a second store. Delete a file and the next sync drops its summary and index entry.
• Spotlight-style, out of your way. Global ⌥Space to summon, hides the moment it loses focus.

---

Architecture

Indexing — every file is routed to the cheapest tier that can actually understand it:

graph LR
    W["watched folders"] --> R{"router:<br/>which tier?"}
    R -->|"plain text, code"| E["embed directly"]
    R -->|"PDF, DOCX, XLSX"| X["extract text"]
    R -->|"receipts, contracts"| S["LLM structured summary"]
    R -->|"scans, images"| V["visual model<br/>embeds the page"]
    R -->|huge files| G["register only,<br/>ripgrep on demand"]
    X --> E
    S --> E
    E --> D[("Qdrant<br/>dense + BM25")]
    V --> D

Search — retrieval is hybrid, and the answer is written from the real files, not from the summaries:

graph LR
    Q["your question"] --> RW["optional<br/>query rewrite"]
    RW --> EM["embed"]
    EM --> DS["dense vector search"]
    EM --> SP["BM25 sparse search"]
    DS --> F["fuse"]
    SP --> F
    F --> RR["cross-encoder<br/>rerank"]
    RR --> RD["read the actual<br/>source files"]
    RD --> A["answer + citations"]

Four models run inside the app — MiniLM for dense embeddings, BM25 for sparse, ColPali for visual pages, and a cross-encoder for reranking. None of them ever call out.

---

How It Holds Up

Magpie is developed against three corpora, each picked to break a different part of the pipeline:

• ReceiptQA — receipt images paired with Q&A. Tests image understanding and identifier extraction: amounts, dates, merchant names.
• A university course catalog — 1,724 courses across 61 departments, split into CSVs by department and by general-education category. Tests row-level CSV retrieval and whether the router sends the right kind of query at the right kind of file.
• A student organization directory — 236 clubs with descriptions and categories, plus each club's uploaded PDFs and Word documents (constitutions, by-laws). Tests mixed-media ingestion at scale.

The answer stage is scored on a hand-written question set with known-correct source files, so a wrong-but-plausible answer still fails:

Read those numbers honestly. This is our own question set on our own corpus, not an external benchmark — we wrote the questions, so treat it as a regression test we haven't gamed rather than proof we beat anyone. It ran on kimi-k2.5, which is not the model the beta ships with. And 35 questions is a small N. The harness is in tests/ if you want to run it on your own files. (The raw per-question dumps aren't published: they were generated over the authors' own documents and quoted them verbatim.)

---

Download

Latest release →

macOS: The First Launch Is Blocked

The beta is unsigned and un-notarized, so macOS quarantines it. This is expected. Either:

xattr -dr com.apple.quarantine /Applications/Magpie.app

…or open System Settings → Privacy & Security, scroll down, and click Open Anyway.

Windows

SmartScreen will warn you. Click More info → Run anyway.

---

First Run

1. Press ⌥Space to summon the window (Alt+Space on Windows).
2. Open Settings → Data → Add folder and point it at something real.
3. Wait for the folder to finish indexing — the row shows live progress.
4. Press ⌥Space again and ask a question.

The first question needs an internet connection. Magpie downloads ~90 MB of embedding models on first use, then works from cache. Indexing large folders also downloads a visual model (500 MB–2 GB) the first time it meets a scanned PDF or image.

Shortcuts

Magpie hides whenever it loses focus, like Spotlight. ⌥Space brings it back.

---

What Works in This Beta

About the local model: Magpie fully supports running inference on-device, but the ~2 GB llama-server runtime isn't bundled in the installer yet and there's no in-app downloader. Selecting Settings → Local will tell you it isn't set up and point you back to Cloud. If you're running from source, just install-llama-server gets you offline inference today.

---

Privacy

What stays local, always:

• Your files. Never uploaded, never copied into another store.
• The index. Qdrant runs as a local binary on loopback. Magpie hard-errors if pointed at a remote cluster — this is enforced in code, not policy.
• All embedding and ranking. The four models above run inside the app and never call out.

What leaves the machine, in Cloud mode only:

• Your question, if query rewriting is on.
• The contents of the files retrieved to answer it, sent to the LLM provider.

That second one is the real boundary — worth knowing before you point Magpie at anything sensitive. In Local mode nothing leaves at all.

On the bundled key: this beta ships with a shared, spend-capped OpenRouter key against a free-tier model so it works out of the box. It's extractable from the binary — assume it's public, and don't rely on it for anything private. Bring-your-own-key and a hosted backend are both planned.

---

Build from Source

git clone https://github.com/mriddyagrawal/Magpie.git
cd Magpie
just sync-environment     # Python deps via uv
just qdrant-install       # local vector database binary
cd frontend && pnpm install

Then run the dev loop:

just qdrant-up                                        # terminal 1
uv run uvicorn src.server:app --port 8765 --reload    # terminal 2
cd frontend && pnpm tauri dev                         # terminal 3

Stack

Python (FastAPI) · Tauri 2 (Rust shell) · React/TS · Qdrant · MiniLM · BM25 · ColPali · cross-encoder reranking

---

Roadmap

Nearest first — the ❌ rows above are the honest backlog:

• Bundle the local model. On-device inference already works from source; it needs the runtime in the installer and an in-app downloader.
• Sign the builds. An Apple Developer ID and a Windows cert remove both scary launch dialogs.
• Bring your own key. Settings → Advanced → API Keys, so nobody depends on the shared beta key.
• Ship Linux. The build exists; it's parked for the beta.
• Token-by-token answer streaming, and cancelling in-flight queries when you retype.
• Auto-update, currently switched off.

Everything we've considered and deliberately deferred — with the reasoning, so we can tell later whether it still holds — lives in Plans/Future Plans.md.

Docs

---

Status

Magpie is a beta. It has been installed and run by a handful of people; expect rough edges, and please open an issue when you find one.

Contributors

Star History

---

License

Magpie is licensed under the GNU Affero General Public License, version 3 (AGPL-3.0-only).

Copyright (C) 2026 Rahul Ranjan Sah and Mridul Agrawal

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

In plain words: anyone may run, read, modify and redistribute Magpie, but a modified version has to carry the same license — and under section 13 that holds even if the modification is only ever run as a network service. Standing up a fork of server/ for other people counts; its users are entitled to the source.

Why AGPL and not MIT. Partly strategy, partly arithmetic: Magpie links PyMuPDF, which Artifex dual-licenses as AGPL-3.0 or a paid commercial license. A permissive license for the combined work was never actually on the table without buying that dependency out.

Commercial use. The AGPL doesn't stop you selling Magpie or running it inside a business; it requires the source to travel with the software. Copyright is held by the two authors, so the same code can also be offered to a customer under a separate commercial license. Contributors sending non-trivial patches should expect to sign a CLA to keep that option open.