{
  "markdown": "<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/logo-dark.svg\">\n  <img src=\"docs/logo.svg\" alt=\"\" width=\"48\" height=\"48\">\n</picture>\n\n# Haypile\n\n**Private document search, for you and your agents.** One binary that watches your folders, indexes every document, and hands your agent the right passages over MCP, each with a file and page citation. Nothing ever leaves your machine.\n\n> Everyone says finding information in your files is like finding a needle in a haystack. Haypile is the haystack that finds its own needles.\n\n![hay demo: add a folder, search by meaning, verify zero outbound connections](docs/demo.gif)\n\n```sh\nbrew install BenyD/tap/hay\nhay add ~/Documents\nclaude mcp add --transport http haypile http://localhost:11500/mcp\n```\n\nThat is the whole setup. Claude Code (or Cursor, or anything that speaks MCP) can now search everything you indexed: `search_documents` returns ranked passages with citations, and the agent answers from them instead of guessing.\n\nIt is a full standalone CLI too:\n\n```sh\nhay search \"termination clause\"\nhay ask \"what did the Meridian contract say about termination?\"\n```\n\nSearch understands meaning, not just words: \"agreement cancellation\" finds termination clauses. Exact identifiers still match exactly. Every result cites its source file and page.\n\n## Install\n\n```sh\nbrew install BenyD/tap/hay\n```\n\nOr grab a binary from [releases](https://github.com/BenyD/haypile/releases), or run the install script:\n\n```sh\ncurl -fsSL haypile.sh | sh\n```\n\nOn Windows, run this in PowerShell:\n\n```powershell\nirm https://haypile.sh/install.ps1 | iex\n```\n\nOne binary, around 56MB, with the embedding model inside. No Python, no Docker, no vector database, no model downloads, no network. Text documents index fully offline; scanned PDFs need a local vision model for OCR (`hay llm setup`).\n\n## Why\n\nAn agent can open any file you point it at. Finding the right one is the problem: grep matches words, not meaning, and a question about termination clauses does not contain the words the contract used. Reading whole documents to find one passage spends the context window the task needed. Cloud document tools fix this by uploading everything to someone else's computer, and self-hosted RAG stacks fix it with Python environments, Docker, and a vector database to babysit.\n\nHaypile is the missing option: **one binary, point it at folders, done.**\n\n- **Agent-ready.** MCP and REST on `localhost:11500`. `search_documents` gives Claude Code, Cursor, or your own scripts cited passages from your documents.\n- **Hybrid search.** Semantic and keyword, merged. Paraphrases match by meaning; case numbers match exactly.\n- **Citations always.** Every result and every answer points to the source file and page.\n- **Always fresh.** Folders are watched. Save a file and it is searchable in seconds.\n- **Verifiably private.** See below.\n\n## Trust commitments\n\nThese are versioned with the code and will not be quietly redrawn:\n\n1. **The open/paid boundary is declared upfront.** Open forever (AGPL-3.0): indexing, search, ask, REST API, MCP, CLI, and the upcoming single-user web UI. The full single-user product, no feature hostages. Paid (later): team features such as auth, roles, audit logs, shared indexes, and a hosted version.\n2. **\"Zero external connections\" is a verifiable feature, not a claim.** `hay status` reports outbound connections; the target is 0. No telemetry. If that ever changes it will be opt-in, documented loudly, and off by default.\n3. **No silent network behavior.** A local-first tool must never phone home to keep working.\n4. **All development happens in this public repo.** No private-repo surprises.\n\n## How it works\n\n```\nfolders -> watcher -> extract (pdf/docx/pptx/md/txt/html/mbox) -> chunk -> embed\n                                                            |\n        you <- citations <- RRF merge <- FTS5 + vector search <- SQLite (one file)\n```\n\nEverything lives in a single SQLite database on your disk, and search is fully self-contained: the embedding model ships inside the binary. Answers (`hay ask`) are generated by whatever OpenAI-compatible local server you already run (Ollama, LM Studio, llama.cpp, Jan). Haypile itself ships no LLM and makes no network calls.\n\n## Set up a folder properly: `hay init`\n\nFor a folder you work in (a case folder, a project, a paper archive), `hay init` writes a per-folder config and wires everything up in one go:\n\n```sh\ncd ~/cases/acme-litigation\nhay init          # three short questions, all with sensible defaults\n```\n\nIt creates `.haypile.yml` (tag and exclude patterns), indexes the folder, optionally writes `.mcp.json` so Claude Code and Cursor can search these docs, and offers `hay llm setup` if you do not have a local LLM yet. `hay init --yes` runs unattended.\n\nEdit `.haypile.yml` by hand anytime. The daemon notices and re-syncs the index within seconds:\n\n```yaml\ntag: acme-litigation\nexclude:\n  - drafts/**\n  - \"*.bak\"\n```\n\n## Ask questions (bring your own LLM)\n\n`hay ask` retrieves the most relevant passages and has a local LLM answer from them, with citations:\n\n```sh\nhay ask \"what did the Meridian contract say about termination?\"\n```\n\nGeneration uses any OpenAI-compatible server you already run (Ollama, LM Studio, llama.cpp, Jan), auto-detected on their usual ports, or set explicitly with `--endpoint` and `--model`. Without one, `hay ask` explains and shows the top passages instead. Search never needs an LLM.\n\nPrefer a cloud model for answers? Bring your own key:\n\n```sh\nhay ask --endpoint https://api.example.com/v1 --key sk-... \"what changed in the lease?\"\n```\n\nThe boundary stays sharp: your documents are indexed locally, always. Opting in sends only the retrieved passages for that one question, to an endpoint you chose, with your key (`HAYPILE_LLM_API_KEY` works too). Keys are refused over plain http to anything that is not localhost.\n\nNo local LLM yet? One guided command gets you there:\n\n```sh\nhay llm setup    # installs and starts Ollama, pulls a model, asks before every download\n```\n\n## Use from Claude Code, Cursor, or your own tools\n\nThe daemon exposes MCP (Streamable HTTP) and REST on `localhost:11500`:\n\n```sh\n# Claude Code\nclaude mcp add --transport http haypile http://localhost:11500/mcp\n\n# Anything that prefers launching a process (stdio transport)\n#   command: hay   args: [\"mcp-stdio\"]\n\n# Plain REST\ncurl -X POST localhost:11500/api/query -d '{\"query\": \"termination clause\"}'\n```\n\nTools exposed: `search_documents` (hybrid search with citations) and `list_sources`. The daemon starts automatically on `hay add` and only ever listens on localhost.\n\n## Commands\n\n```\nhay init [folder]        per-folder setup: config, index, editor wiring\nhay add <path>           index a folder or file and watch it for changes\nhay search \"<query>\"     hybrid retrieval, results with citations\nhay ask \"<question>\"     answer from your documents, with cited sources\nhay list                 indexed folders and document counts\nhay remove <path>        un-index a folder\nhay status               daemon state, model info, outbound connections (target: 0)\nhay web                  open the local web UI in your browser\nhay serve                run the daemon (REST API + MCP on localhost:11500)\nhay llm setup            guided local LLM setup for hay ask\n```\n\n## Roadmap\n\n| Version | Scope |\n|---|---|\n| v0.x (now) | CLI, REST API, MCP server, `hay web` local UI. Markdown, text, PDF, docx, pptx, HTML, mbox email. Scanned-PDF OCR via your local vision LLM. |\n| v1.x | Bundled OCR (no LLM required), Windows installer polish |\n| v2 | Optional larger embedding models, ANN index for very large corpora |\n| Pro | Team layer for offices: auth, roles, audit logs, shared indexes (paid) |\n\nRoadmap, decisions, and trust commitments in detail: [docs/ROADMAP.md](docs/ROADMAP.md).\n\n## Development\n\n```sh\ngo build ./cmd/hay     # build the binary\ngo test ./... -race    # run tests (green before any merge)\n```\n\nSemantic search uses an embedding model that release builds carry inside the binary. Dev builds load it from disk instead, so the weights stay out of git:\n\n```sh\n./hack/fetch-model.sh                    # one-time download (also quantizes)\ngo build -tags bundled ./cmd/hay         # release-style: model in the binary\nHAYPILE_MODEL_PATH=internal/embed/bundled/model.safetensors ./hay   # dev\n```\n\nWithout the model, everything still works in keyword-only mode.\n\nThe web UI (`hay web`) lives in [webui/](webui/) as a small Vite + Preact app; its built output is committed under `internal/webui/dist` and embedded in the binary, so `go build` alone always ships the current UI. Touch the UI with:\n\n```sh\ncd webui && npm install\nnpm run dev      # live dev server, proxies /api to a running daemon\nnpm run build    # writes internal/webui/dist (commit the result)\n```\n\nRetrieval quality is measured, not vibes: [eval/](eval/) holds a query set with expected results that runs on every retrieval-affecting change.\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. It covers the dev workflow, the rule that the privacy contract (zero outbound, bundled model, localhost only) must stay intact, how contributions are licensed, and the DCO sign-off (`git commit -s`) that CI enforces.\n\n## Security\n\nFound a vulnerability? Please report it privately, not as a public issue. See [SECURITY.md](SECURITY.md) for the disclosure process and what is in scope.\n\n## License\n\n[AGPL-3.0](LICENSE). Free forever for individuals. The AGPL keeps it free for every actual user while requiring anyone offering Haypile as a service to open-source their changes.\n",
  "bytes": 9647,
  "sha": "4507e544bf92205ad40d737abc05d69f946a47e863fcc98e6aa43c881e30d65e",
  "repo_slug": "benyd/haypile",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_benyd_haypile_5d9f6f27/readme"
}