https://github.com/user-attachments/assets/0db212bb-82be-494d-aabd-fbb224d211fd
Why FilDOS
Cloud file-AI products require you to upload your files to use AI features. Every
document, photo, and note you hand over teaches someone else's model and sits
on someone else's servers.
FilDOS runs the other way around: the app, the index, and the models all live
on your personal machine. Embeddings, search, the knowledge graph, and the assistant
chat are computed on-device, nothing leaves your computer unless you
explicitly connect a cloud drive. The whole thing is MIT licensed, so the
privacy story is something you can read in the source, not something you have
to take on faith.
What FilDOS does
- A real file manager first. List, grid, gallery, and column views,
resizable columns, inline rename, drag-and-drop, undo, tags, recents,
per-folder view memory, and Quick Look on Space. The basics work before any
AI does.
- Search by meaning. Ask for "receipts from tax season" or "photos from the
Japan trip" and FilDOS finds files by what's in them, not just their names.
Text, PDFs, DOCX, pictures, audio, and video are indexed with one on-device
model (EmbeddingGemma 2), and a hit opens at the matching page or moment.
When nothing matches, search says so instead of showing the nearest noise.
- Private, on-device AI. Indexing and embedding run locally on ONNX
Runtime (CPU); nothing is uploaded, and the index lives in a local database.
- Chat with your files. An on-device LLM (llama.cpp) that can
@file and
#folder mention your data, run /find searches, and act on files (create,
copy, move, rename, delete to the Trash). Every action is recoverable:
deletes go to the OS Trash, nothing is overwritten, and each action is shown
as it happens. Every exchange is saved so you can resume it later.
- Canvas. A GPU-rendered knowledge graph of your files, built from
embedding similarity, extracted entities, and temporal sessions. A visual
answer to "how does this connect to the rest of my work."
- Your clouds, one window. Browse Google Drive, Dropbox, OneDrive, Amazon
S3, and IPFS alongside local folders through the same interface.
- Hide from AI. Exclude specific files, folders, or extensions from
indexing and chat so the assistant never sees what you don't want it to.
- Bring your own model. A built-in catalog of local models (Llama, Qwen,
Gemma, Phi, Mistral, DeepSeek, and more), or paste any GGUF from Hugging
Face, everything runs on your own hardware.
Repository layout
src/ The desktop app: Electron main / preload / renderer
shared/ Types and IPC channel names shared by every layer
main/ Main process: filesystem, database, and the AI layer
preload/ contextBridge: the only surface the renderer can call
renderer/ The React app
docs/ Product docs (Mintlify)
website/ The landing site (Next.js)
A deeper tour of the architecture, the IPC contract, the database layer, and
each AI subsystem lives in .claude/CLAUDE.md.
Getting started
FilDOS is in beta. Grab a packaged build from
Releases — macOS (.dmg,
Apple Silicon and Intel) and Linux (.AppImage, .deb) — or build from source
with the steps below.
Prerequisites
- Node.js 22 or newer (required the app relies on
node:sqlite, which needs
Node 22 / Electron ≥ 35)
- npm
Run the desktop app
git clone https://github.com/ahmedfahim21/FilDOS.git
cd FilDOS
npm install # also installs the git pre-commit hook
npm run dev # electron-vite dev server with HMR
Cloud-provider OAuth credentials (Google Drive, Dropbox) are optional and only
needed if you want to test those integrations locally. Copy .env.example to
.env and fill in the values.
Build a production bundle
npm run build # output in out/
npm start # preview the production build
Development
npm run typecheck # tsc for the node (main/preload) and web (renderer) projects
npm run lint # eslint (flat config)
npm test # vitest — unit and integration tests
npm run test:watch # vitest in watch mode
npm run test:e2e # build, then run the Playwright smoke test on the packaged app
Tests live beside the code as *.test.ts. The filesystem service tests are
true integration tests that exercise real files in a temporary sandbox. The
end-to-end test launches the built Electron app and asserts the shell boots;
on a headless Linux machine, run it under xvfb-run.
Please run npm run lint, npm run typecheck, npm test, and npm run build
before opening a pull request. CI runs lint, typecheck, unit/integration
tests, and the end-to-end smoke test on Ubuntu, macOS, and Windows, plus the
AI eval smoke suite on Ubuntu. See
CONTRIBUTING.md for the full workflow.
Tech stack
- Electron, React, TypeScript, electron-vite
- Tailwind CSS v4 and Radix primitives
- SQLite (
node:sqlite) with Drizzle ORM
@huggingface/transformers on onnxruntime-node for on-device embeddings
(EmbeddingGemma 2) and entity extraction- MiniSearch (BM25) for keyword search
node-llama-cpp for the on-device assistant chat@cosmos.gl/graph (GPU/WebGL) for the Canvas knowledge graphopendal for the S3, IPFS, and OneDrive backends- Vitest and Playwright for testing
Contributing
Contributions are welcome. Start with CONTRIBUTING.md, and
note that this project follows a Code of Conduct. Design
and UI work should follow .claude/brand-guidelines.md.
Security issues should go through SECURITY.md rather than a
public issue.
License
MIT © Fahim Ahmed
