Stashbase

StashBase

Turn local files into searchable context for Agents.

[](https://stashbase.ai) [](https://github.com/liliu-z/stashbase/releases/latest) [](#status) [](LICENSE) [](https://discord.gg/zsRZH4PTq9)

Much of your best context lives in local files that Agents can't easily search — papers, contracts, scanned documents, recordings. 📂 Open a folder in StashBase and its supported contents become searchable:

• 📄 Prepare: extract searchable text from PDFs, DOCX files, images, audio, and video.
• 🔎 Search: find relevant context by meaning, not just keywords.
• 🤖 Connect: share searchable context across Claude, Codex, and other MCP clients.

Your folders remain the source of truth; StashBase adds a search index that can be rebuilt from them.

The core idea:

Local files -> prepared text -> search index -> MCP -> Agents

---

🚀 Demo

Open this repo in StashBase and ask the built-in Agent: How is this project designed?

---

💡 Try It

StashBase's primary platforms are macOS 12+ (Apple Silicon) and Windows 10+ (x64). A community-supported Linux build is also available for x86_64 Debian 12+ / Ubuntu 22.04+.

macOS

brew install --cask liliu-z/stashbase/stashbase

Windows

Download the latest StashBase-*-win-x64.exe installer from Releases, then run it.

Linux

Download the latest StashBase-*-linux-amd64.deb asset from Releases, then install it:

sudo dpkg -i ./StashBase-*-linux-amd64.deb

First Run

> Don't have an embedding API key? In-app keyword search works without one. Join our Discord to ask about evaluation access.

1. Open an existing local folder, or create a new one from the native folder picker.
2. Add an OpenAI or OpenRouter API key when prompted if you want semantic search.
3. To transcribe audio or video, download a speech model from Settings -> Transcription. Small (465 MiB) is the default; Tiny (74 MiB) and Base (141 MiB) are lighter options. Transcription runs entirely on your machine, with no API cost, and you can cancel or rerun it while viewing the file.
4. Connect Claude, Codex, or another MCP client from Settings -> MCP.
5. Ask the Agent to search or use your local files.

Your library is opt-in: only folders you open in StashBase are indexed. You can remove a folder from the library at any time; StashBase clears its index but never deletes the folder from disk.

Use File → New Window or Cmd/Ctrl+Shift+N to keep different folders and tools side by side. Window close follows VS Code's platform shortcuts; Cmd/Ctrl+W continues to close the active document tab.

---

What It Does

StashBase has two core jobs: prepare files and index their contents.

Prepare

Some formats need preparation before their contents can be searched. StashBase keeps the original files in place and creates derived text only where needed for search and Agent access.

| Format | Visible source | Indexed text | |---|---|---| | Markdown | The Markdown file | Source text | | HTML | The HTML file | Clean text extracted from the HTML | | PDF | The original PDF | Derived Markdown | | DOCX | The original DOCX | Derived HTML | | Images | The original image | OCR text | | Audio and video | The original media | Audio track transcribed locally to timestamped Markdown |

For PDF, DOCX, audio, and video, Agents read the derived text while the original remains the visible source file. Audio and video play directly when supported; otherwise, StashBase creates a compatible local audio preview. Large files dragged into the app stream to disk instead of being held entirely in memory. See [Architecture](design-docs/architecture.md) and [Preparation](design-docs/design/preparation.md) for the product and system contracts.

Index

StashBase builds semantic and keyword search over:

• Markdown and HTML text
• PDF-derived Markdown
• DOCX-derived HTML
• OCR text from images
• timestamped transcripts from audio and video

Search results point back to the user-visible source file, not hidden app data.

Background preparation is intentionally quiet. Browsing a folder should feel like browsing files, not watching an indexing job. If preparation fails, StashBase shows a lightweight failure marker and lets you retry. Readiness matters most when you search, so that is where StashBase shows how much of your content is ready.

---

MCP

MCP is the main interface between StashBase and Agents.

While the StashBase app is running, a local MCP server makes the same library available to external clients and the built-in Agent panel.

Core tools:

• library_info - return the default folder home, opened folders, optional folder descriptions, and embedder status.
• search_library - search the library, optionally scoped by folder or path prefix.
• reindex - reconcile disk changes and make updated files searchable.

StashBase also exposes bounded file helpers for opened folders:

• list_directory
• read_file
• write_file
• edit_file
• move_file
• delete_file

These helpers exist for Agent clients that run in a sandbox and cannot directly access the user's host files. They are not a general-purpose filesystem API.

Connect a Client

The normal path is Settings -> MCP. StashBase can write the MCP config for supported clients or copy the stdio snippet for clients that manage config themselves.

For manual stdio setup, URL-based clients, Docker access, ports, CORS boundaries, and token rotation, see [Advanced MCP configuration](docs/mcp-configuration.md).

---

Built-In Agent Panel

StashBase includes a built-in panel for running local Agent CLIs such as Claude Code and Codex against the current folder.

The panel is a convenient client of the same MCP server, not a separate knowledge base. It adds:

• Sessions run in the current folder, next to the files they work on.
• Tool calls and file edits can be reviewed in the app.
• Session history stays in the Agent CLI's normal storage.

---

Storage Model

Local files are the source of truth.

~/.stashbase/config.json          # app-level config, including transcription preferences

/
  paper.pdf                       # user file

/derived.nosync/         # derived text, assets, transcript work, media previews
/models/whisper/         # explicitly downloaded local speech models
/vector-store.nosync/    # Milvus Lite vector store
/state/state.db          # conversion failures and local app state

Removing a folder from the library clears StashBase's app-owned state for that folder. It does not delete the folder or its files from disk.

---

Design Docs

The design docs explain the product intent, system contracts, and contribution areas without duplicating the source tree:

• [Design docs guide](design-docs/README.md) - contribution map and maintenance rules
• [Overview](design-docs/overview.md) - product thesis
• [Principles](design-docs/principles.md) - durable decision rules
• [Architecture](design-docs/architecture.md) - system boundaries and invariants
• [Product direction](design-docs/product-direction.md) - intended product shape

---

Build From Source

For contributors and developers building locally, and for platforms without a prebuilt installer.

git clone https://github.com/liliu-z/stashbase
cd stashbase
pnpm install
pnpm setup:python

# Build the renderer and run Electron
pnpm build:web
pnpm electron

# Development mode
pnpm dev

# Build a distributable app for your platform
pnpm dist        # macOS
pnpm dist:win    # Windows
pnpm dist:linux  # Linux

# Optional: include the local PDF/OCR extractor sidecar
pnpm build:python-extract-sidecar

Before opening a PR:

pnpm check

---

Status

Early alpha.

Primary support:

• macOS arm64
• Windows 10+ x64

Community-supported:

• Linux x86_64 Debian 12+ / Ubuntu 22.04+

Reasonably stable:

• Local folder library model
• Markdown, HTML, PDF, and image preview
• PDF extraction, image OCR, and local audio and video transcription, with persisted failures and retry
• Semantic and keyword search
• MCP server and client connectors
• Bounded file helpers for sandboxed Agents
• Built-in Claude Code / Codex panel

Where We Need Help

• Agent panel polish
• Search filters and ranking controls
• Long-running conversion and recovery edge cases
• Packaging polish across platforms

---

Contributing

Small focused PRs are preferred. Open an issue before larger changes so scope and direction can be discussed first.

Not sure where to start? Pick something from [Where We Need Help](#where-we-need-help), or open [design-docs/](design-docs/) in StashBase and ask the Agent — or just ask us.

See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, validation, and release-maintainer notes.

---

About

StashBase is an independent open-source project built by Li Liu, who works on Milvus at Zilliz and brings years of vector-retrieval experience to making local files searchable in Agent workflows.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: liliu-z
• Source: liliu-z/stashbase
• License: Apache-2.0
• Homepage: https://stashbase.ai

Install and usage instructions live in the source repository linked above.