Ferret

Ferret is a local-first web assistant for private workspaces. With explicit user permission, it can inspect selected local folders, help locate hard-to-find files by name, path, or content, and use a lightweight on-device AI model to explain what a file does, summarize its purpose, and help users understand code directly in the browser.

The core idea behind Ferret is simple: a web application should be able to behave like a personal assistant for a user's local files without forcing those files into the cloud. Instead of uploading sensitive code, research, or internal documents to remote AI services, Ferret keeps the experience local. The user chooses which folders to grant access to, search happens in the browser, and AI explanations are generated locally on the device.

This makes Ferret useful for developers exploring unfamiliar codebases, researchers navigating large document collections, and anyone who needs help understanding complex local files while maintaining privacy and control.

Why Ferret

Reading through a large project or an unorganized folder of files can take hours. Search alone is often not enough: you may find the right file, but still need help understanding what it does, how it connects to the rest of the workspace, or why it matters.

Ferret is designed to bridge that gap. It combines local file discovery with local AI explanation so users can search, open, inspect, and ask questions about their own files in one place — without sending their workspace data to a remote backend.

Features

• Permission-based local access: Ferret only reads folders the user explicitly approves.
• Workspace search: Find files by name, path, or indexed content using hybrid BM25 + semantic search.
• Built-in file viewer: Open and inspect local files directly in the browser.
• Private AI assistance: Ask Ferret to explain a file, summarize it, or help interpret code.
• Local-first architecture: Search, indexing, and AI inference happen locally in the browser.
• No cloud dependency for file understanding: Workspace contents are not sent to a remote AI API.
• On-device semantic embeddings: LiteRT.js runs a .tflite embedding model in a Web Worker (WebGPU-accelerated with WASM fallback) to power vector similarity search.

Example Workflow

A developer downloads a large, undocumented software project and opens Ferret in the browser. They grant access to the project folder, search for "authentication", open the most relevant file, and ask Ferret: "How does the login flow work here?"

Ferret searches the approved local workspace, opens the file, and returns a plain-English explanation generated by a lightweight local model running directly in the browser.

Getting Started

Make sure you have Bun installed, then install dependencies and start the development server:

bun install
bun run dev

Open http://localhost:3000 in your browser.

WASM Runtime Setup

Ferret uses LiteRT.js for on-device .tflite inference (semantic embeddings and file classification). The LiteRT WASM runtime files must be present at public/wasm/ so the browser can load them statically.

These files are not committed to the repository (only a .gitkeep placeholder is). They are automatically copied from node_modules/@litertjs/core/dist/ into public/wasm/ by the postinstall script when you run bun install. If you ever see a blank inference screen, re-running bun install will fix it.

For contributors: Do not manually place files in public/wasm/. Let the scripts/copy-wasm.mjs postinstall script handle it. This ensures all contributors are always on the correct runtime version that matches the installed @litertjs/core package.

Usage

1. Connect a folder
   Choose a local folder you want Ferret to inspect. Your browser will ask for permission before access is granted.

2. Search the workspace
   Search by file name, path, or content to locate relevant files quickly. Results are ranked using a hybrid BM25 + cosine similarity algorithm powered by LiteRT embeddings.

3. Open a file
   Browse and inspect the file directly in the built-in viewer.

4. Ask Ferret for help
   Use the built-in AI to explain what a file does, summarize its purpose, or help interpret code and technical content. LiteRT classifies the file type first so WebLLM uses the most relevant system prompt.

LiteRT & WebGPU Badge

A small status badge in the UI shows the current state of the LiteRT inference worker (Loading, Ready, etc.) and whether it is running on WebGPU (fast, GPU-accelerated) or WASM (CPU fallback). This gives users transparency about their device capabilities without requiring any configuration.

Privacy

Ferret is built around local privacy and controlled access:

• Folder access is granted explicitly by the user.
• Only approved local workspaces are searchable.
• File indexing happens locally in the browser.
• AI inference runs locally after model assets are downloaded and cached.
• Workspace contents are not sent to a cloud AI service for explanation.

Contributing

Contributions are welcome.

• Open an issue to report bugs or suggest features.
• Fork the repository, make your changes, and submit a pull request.
• Keep changes focused, documented, and easy to review.