Kagaz (काग़ज़, “paper”) is a local-first document vault manager for macOS. It names, files and tags your documents by convention — no database, no cloud, and no proprietary format standing between you and your files.
Open-source CLI, MIT-licensed & free forever · Nothing ever leaves your Mac
--json everywhere + MCPAll defined by a single vault.yaml — never hardcoded. Kagaz enforces the convention so every document lands where you expect and stays findable.
Ingest a document and Kagaz derives its conventional name and folder from your vault.yaml — then previews the move before touching a byte.
A searchable index built from the files themselves. Query by person, company, area, doctype, tag, fiscal period, or free text — all offline.
Text-layer PDFs, images, and scans via Apple Vision — plus a rules classifier that needs zero downloads. It gets better as you opt into more, never different.
Reads .docx / .xlsx / .pptx in-process — no Microsoft Office, no external tool. Legacy .doc/.rtf/.xls handled too.
Writes real Finder tags validated against a controlled vocabulary. An off-vocabulary tag is refused before it's written — no drift, no orphans.
kagaz lint reports convention violations — wrong folders, bad grammar, missing lifecycle tags — and --fix applies only provably safe repairs.
Write a vault.yaml and category folders at ~/Documents. Or explore a populated demo.
OCR → classify → propose. Every move is previewed and needs your approval first.
$ kagaz ingest ~/Downloads/*Query by person, company, doctype, tag or fiscal period — or just free text.
$ kagaz find "acme"Lint the tree, regenerate INDEX.md + AGENTS.md, roll anything back.
Every mutating command follows the same path: propose → preview → approve → execute with a manifest. Nothing changes silently.
A native SwiftUI menu-bar app that holds zero vault logic of its own — it shells out to the kagaz CLI over --json, exactly like you would from a terminal. Convenience over the CLI, never a gate in front of it.
vault.yaml with live validation.Kagaz was designed so an AI agent can drive it as safely as you can — with the same previews, the same audit trail, and no hidden state.
--json on every command — a stable, documented envelope with exit codes a script can branch on.kagaz mcp exposes the vault to any MCP-capable client over stdio.AGENTS.md — regenerated by kagaz index, teaching an agent exactly how this vault is organized.These are enforced in code, checked at call time — not settings you can quietly turn off.
The only network call anywhere is an explicit, opt-in kagaz model pull. Classification and OCR run on-device or against a verified localhost endpoint.
A “move” copies, verifies by SHA256, then retires the source into a staging folder only you empty. Delete Kagaz and every file is right where it was.
Each mutating command writes a manifest before the first byte moves. kagaz rollback reverses it — safe to run twice.
Resolving a confidential document to send it out of the vault always requires explicit confirmation and always writes an audit line — no flag bypasses either.
Fifteen focused subcommands, each with a stable --json shape and documented exit codes. Read-only queries and reversible mutations, clearly separated.
kagaz init | Create a new vault |
kagaz ingest | OCR → classify → propose → file |
kagaz find | Query the vault |
kagaz lint | Report & fix convention violations |
kagaz rollback | Reverse any manifest |
kagaz mcp | Run the stdio MCP server |
The kagaz CLI, MCP server and helpers are MIT-licensed and free — nothing is withheld or degraded to sell the app. The Mac app is a separate, paid product… but it's free for now.
The complete vault manager — terminal & agents
--json everywhereThe native menu-bar app over the CLI
The CLI stays free and open source regardless — a terminal user loses nothing by not buying the app.
Requires Apple silicon (M1 or later) and macOS 15 (Sequoia) or later.
Installs the kagaz CLI, the kagaz-mcp server and the on-device OCR helper. Then run kagaz doctor to check your setup.
.dmg download will land here when the app is ready — free while it's in beta.
Launching soon
Neither. There's no Kagaz account and no backend — nothing you file or search is ever sent anywhere. Your files stay as ordinary files on disk (or in iCloud Drive, if that's where ~/Documents lives). It's not a general file manager either: it only touches documents that fit its doctype catalog and convention.
Both semantic classifier tiers are Apple-silicon-only: Apple Vision's accurate-mode OCR and Apple Foundation Models' on-device generation are arm64 frameworks. Rather than ship an Intel build stuck in a permanently degraded rules-only mode, Kagaz makes Apple silicon a deliberate, permanent requirement.
No. The offline rules-based classifier is always available and is what most of Kagaz's own tests run against. Apple's on-device tiers add no download at all. MLX and Ollama are opt-in for people who want them.
The CLI is the only thing that ever mutates a vault. The Mac app holds zero vault logic — it shells out to kagaz ... --json and parses the output, exactly like a human or any other agent. It's convenience over a CLI that's complete on its own.
Kagaz for Mac is a paid, closed-source product, but it's free for now while it's pre-1.0. We'll charge once there's a more stable version. The kagaz CLI is and always will be free and open source (MIT) — nothing in it is withheld to sell the app.
Local-first, convention-enforcing, and reversible by design. Free and open source — with a native Mac app that's free while it's in beta.