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.
• 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.

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.

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.

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.

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.