localmd

You write. AI connects. All in your local folder.

An agent lives in your folder, a wiki grows around your files. It reads the PDFs, EPUBs and notes already there, reaches the tabs open in your browser, and writes linked Markdown beside them. Every citation clicks back to the exact paragraph, and every change waits for your yes.

▶ Try it now — no install, no account, no key

It is a web page. Open it, click Try the demo, ask a question about a real 43-page paper, then click a citation and land on the paragraph it came from. Nothing to clone first; come back here if you like it.

---

There is no backend. The app is a static page: it reads and writes your files through the File System Access API, and it talks to whichever model provider you gave it a key for. Nothing is uploaded, because there is nowhere to upload to.

That last sentence is the reason this repository exists. "Your files are not uploaded" is a claim, and claims about privacy are worth exactly as much as your willingness to take someone's word for it. Here you can read the code, run it yourself, and watch the network tab.

This is the whole application and all of it is free — the agent, the tools, the document indexes, git and GitHub sync, MCP servers, the browser extension bridge. There is no paid tier, no account, and nothing held back for a hosted version. localmd.app is simply this repository, built and deployed.

Bugs and ideas → the issues on this repository.

What it does

• Markdown, in a folder you already have. File tree, editor, preview, [[wikilinks]], backlinks, a force-directed graph, full-text search. It adapts to your folders, not the other way round. There is no import, because there is no format to import into.
• An agent that works in your files. It lists, reads, searches, writes and edits, with a review panel that shows every change as a diff before or after it lands. Bring a key for Anthropic, OpenAI, DeepSeek, Gemini, xAI, Groq, Qwen, GLM, Kimi, MiniMax, or any OpenAI-compatible endpoint.
• PDFs and EPUBs with citations that click back. Documents are parsed into a block-level index, so when the agent quotes a source it writes a token that renders as a chip — click it and you land on that paragraph, highlighted.
• Version history that is just git. isomorphic-git in the browser, writing a real .git your terminal understands. Optional sync to GitHub over the REST Git Data API (git's smart-HTTP has no CORS, so mirroring objects is the way a page can do this at all).
• Tools are data, not code. Web search ships with it. Beyond that, you or the agent can author an HTTP tool against any API, or connect an MCP server — a spec, not a release.
• Your browser, as a third source. The companion extension — localmd Connect, open source too — lends the agent your own signed-in Chrome: open a tab, read a page, click, type. What it brings back lands in the folder as a source, citable like any PDF. There is no catalogue of supported sites; the agent works one out live and can save what it learned as a skill in your folder.
• Installable and offline. It is a PWA; everything is cached on your device.

Requirements

Chrome or Edge. Reading and writing a folder you picked takes the File System Access API, and only Chromium browsers have it. Firefox has called it harmful; Safari offers only a sandboxed store.

You supply your own API key. It is kept in your browser and sent straight to the provider you chose, never through us — there is no "us" in the request path. Be precise about what that means: your files stay in your folder, and the text you send to a model goes to that model's provider.

Custom gateways often refuse browser CORS; the providers' own endpoints work.

Running it

npm run build writes a folder of static files. Serve it over https from anywhere that serves static files — there is nothing to configure, no environment to set and no server to keep running. Whatever your host asks for, the answer is npm run build and dist.

No host-specific config files ship here. localmd.app runs on Vercel, which is also what api/ is written for — the small proxy behind the no-key trial. That directory is the one part that is not just static files, and a deployment without it simply has no trial; everyone brings their own key, which is the normal path anyway.

(No Dockerfile, on purpose: a container whose whole job is serving a folder of files is more moving parts than a build plus any static host, not fewer.)

Deploying it is yours to run. Bug reports about the app are welcome in the issues; "my host is not serving it" is a question about your host, and this is a solo project with no support commitment behind it.

npm install
npm run dev        # http://localhost:5173
npm run build      # static output in dist/ — deploy anywhere with https
npm run typecheck
npx vitest run
npm run test:e2e   # Playwright, drives system Chrome

Production needs https: the File System Access API requires a secure context.

What localmd.app adds

Nothing you cannot have. It is this repository, deployed — the same build, with two things that only make sense for one address: an anonymous page-view count (same-origin, so a copy you host reports to your origin and not ours), and a free trial that spends our own API budget so a first-time visitor can try the agent without a key. api/ is the small proxy behind that trial; deploy without it and everyone brings their own key, which is the normal path anyway.

Architecture

A static Vue 3 SPA (Vite + Pinia + Tailwind). Reading order for the code:

src/lib/fs.ts	the File System Access layer: KB-relative paths → handles, atomic writes
src/agent/	the tool loop, the tool definitions, the system prompt
src/lib/docindex/	PDF/EPUB/Markdown → block-level indexes, and the id invariant that keeps citations resolving
src/lib/git*.ts, src/lib/github.ts	isomorphic-git over a File System Access adapter; GitHub sync
src/stores/	Pinia: KB, files, chat sessions, settings, tools, MCP
docs/	design notes and post-mortems, including docs/token-optimization.md
CONTEXT.md	the glossary — read it before renaming a concept
AGENTS.md	the working agreements: what the constraints are and why

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for where things go and what a patch needs. AGENTS.md has the working agreements behind the code, and is worth handing to a coding agent if you use one. Security reports go through SECURITY.md, privately.

License

MIT — see LICENSE. The licence covers the code, not the name "localmd" or its logo, which identify the hosted service at localmd.app; see TRADEMARK.md. Fork freely — please give your copy its own name.